- Accessible, usable docs are worth something in ROI
- https://www.writethedocs.org/
- https://read-the-docs.readthedocs.io/en/latest/
- https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800
- Dockerfile that extends from readthedocs/build:latest (which has the GBs of latex necessary to run `make latexpdf` for all you PDF lovers out there)
- https://github.com/yoloseem/awesome-sphinxdoc
- There are various Sphinx extensions for optionally including generated API docs for various languages
- If you add the extensions you want installed to your requirements.txt or environment.yml, ReadTheDocs will install those for every build. You can also create (and maintain) a custom Docker image with all of the docs building dependencies installed (e.g. requirements_dev.txt and/or docs/requirements.txt)
- https://kernel.readthedocs.io/en/latest/kernel-documentation.html
- This says "Copyright 2016"? That's set in conf.py
I keep a tools doc in ReST:
- https://westurner.github.io/tools/#sphinx
- https://westurner.github.io/tools/#docutils
I'll just CC those sections here
wrapped in a Markdown fenced code block
```rst
.. index:: Docutils
.. _docutils:
Docutils
~~~~~~~~~~~~~~~~~~~
| Homepage: http://docutils.sourceforge.net
| PyPI: https://pypi.python.org/pypi/docutils
| Docs: http://docutils.sourceforge.net/docs/
| Docs: http://docutils.sourceforge.net/rst.html
| Docs: http://docutils.sourceforge.net/docs/ref/doctree.html
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html
| Src: svn http://svn.code.sf.net/p/docutils/code/trunk
Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`
lightweight markup language into a doctree (~DOM)
which can be serialized into
HTML, ePub, MOBI, LaTeX, man pages,
Open Document files,
XML, JSON, and a number of other formats.
.. index:: Sphinx
.. _sphinx:
Sphinx
~~~~~~~~~~~~~~~~~
| Wikipedia: `<https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
| Homepage: https://pypi.python.org/pypi/Sphinx
| Src: git https://github.com/sphinx-doc/sphinx
| Pypi: https://pypi.python.org/pypi/Sphinx
| Docs: http://sphinx-doc.org/contents.html
| Docs: http://sphinx-doc.org/markup/code.html
| Docs: http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role
| Docs: http://pygments.org/docs/lexers/
| Docs: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
| Docs: https://github.com/yoloseem/awesome-sphinxdoc
Sphinx is a tool for working with
:ref:`ReStructuredText` documentation trees
and rendering them into HTML, PDF, LaTeX, ePub,
and a number of other formats.
[...]
```
FWIW, ReadTheDocs can host multiple versions of the docs according to the repo
tags you specify in the web admin.
There may be a way to use the RTD JS UI for selecting versions
with the docs hosted on your own server?
Such as https://www.kernel.org/doc/html/latest/
- https://github.com/torvalds/linux/blob/master/Documentation/conf.py
- https://github.com/torvalds/linux/blob/master/Documentation/Makefile
- https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/index.rst
- https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/sphinx.rst
- https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/kernel-doc.rst
- https://www.kernel.org/doc/html/latest/
- https://www.kernel.org/doc/html/latest/doc-guide/
- https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install
- https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments
- https://www.writethedocs.org/
- https://read-the-docs.readthedocs.io/en/latest/
- https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800
- Dockerfile that extends from readthedocs/build:latest (which has the GBs of latex necessary to run `make latexpdf` for all you PDF lovers out there)
- https://github.com/yoloseem/awesome-sphinxdoc
- There are various Sphinx extensions for optionally including generated API docs for various languages
- If you add the extensions you want installed to your requirements.txt or environment.yml, ReadTheDocs will install those for every build. You can also create (and maintain) a custom Docker image with all of the docs building dependencies installed (e.g. requirements_dev.txt and/or docs/requirements.txt)
- https://kernel.readthedocs.io/en/latest/kernel-documentation.html
- This says "Copyright 2016"? That's set in conf.py
I keep a tools doc in ReST:
- https://westurner.github.io/tools/#sphinx
- https://westurner.github.io/tools/#docutils
I'll just CC those sections here
wrapped in a Markdown fenced code block
```rst
.. index:: Docutils
.. _docutils:
Docutils
~~~~~~~~~~~~~~~~~~~
| Homepage: http://docutils.sourceforge.net
| PyPI: https://pypi.python.org/pypi/docutils
| Docs: http://docutils.sourceforge.net/docs/
| Docs: http://docutils.sourceforge.net/rst.html
| Docs: http://docutils.sourceforge.net/docs/ref/doctree.html
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html
| Src: svn http://svn.code.sf.net/p/docutils/code/trunk
Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`
lightweight markup language into a doctree (~DOM)
which can be serialized into
HTML, ePub, MOBI, LaTeX, man pages,
Open Document files,
XML, JSON, and a number of other formats.
.. index:: Sphinx
.. _sphinx:
Sphinx
~~~~~~~~~~~~~~~~~
| Wikipedia: `<https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
| Homepage: https://pypi.python.org/pypi/Sphinx
| Src: git https://github.com/sphinx-doc/sphinx
| Pypi: https://pypi.python.org/pypi/Sphinx
| Docs: http://sphinx-doc.org/contents.html
| Docs: http://sphinx-doc.org/markup/code.html
| Docs: http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role
| Docs: http://pygments.org/docs/lexers/
| Docs: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
| Docs: https://github.com/yoloseem/awesome-sphinxdoc
Sphinx is a tool for working with
:ref:`ReStructuredText` documentation trees
and rendering them into HTML, PDF, LaTeX, ePub,
and a number of other formats.
[...]
```
FWIW, ReadTheDocs can host multiple versions of the docs according to the repo
tags you specify in the web admin.
There may be a way to use the RTD JS UI for selecting versions
with the docs hosted on your own server?
Such as https://www.kernel.org/doc/html/latest/
- https://github.com/torvalds/linux/blob/master/Documentation/conf.py
- https://github.com/torvalds/linux/blob/master/Documentation/Makefile
- https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/index.rst
- https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/sphinx.rst
- https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/kernel-doc.rst
- https://www.kernel.org/doc/html/latest/
- https://www.kernel.org/doc/html/latest/doc-guide/
- https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install
- https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments
On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <corbet@xxxxxxx> wrote:
On Tue, 23 Apr 2019 15:01:32 +0200
Peter Zijlstra <peterz@xxxxxxxxxxxxx> wrote:
> But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> give me anything in return. There is no upside, only worse text files :/
So I believe it gives even you one thing in return: documentation that is
more accessible for both readers and authors. More readable docs should
lead to more educated developers who understand the code better. More
writable docs will bring more people in to help to improve them. The
former effect has been reported in the GPU community, where they say that
the quality of submissions has improved along with the docs. The latter
can be observed in the increased number of people working on the docs
overall, something that Linus noted in the 5.1-rc1 announcement.
Hopefully that's worth something :)
Thanks,
jon
-- dm-devel mailing list dm-devel@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/dm-devel
