- 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-485... - 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:
```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)%3E%60_ | 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.
Sphinx extends :ref:`Docutils` with a number of useful markup behaviors which are not supported by other ReStructuredText parsers.
Most other ReStructuredText parsers do not support Sphinx directives; so, for example,
* GitHub and BitBucket do not support Sphinx but do support ReStructuredText so ``README.rst`` containing Sphinx tags renders in plaintext or raises errors.
For example, the index page of this :ref:`Sphinx` documentation set is generated from a file named ``index.rst`` that referenced by ``docs/conf.py``, which is utilized by ``sphinx-build`` in the ``Makefile``.
* Input:
.. code:: bash
_indexrst="$WORKON_HOME/src/westurner/tools/index.rst" e $_indexrst
# with westurner/dotfiles.venv mkvirtualenv westurner we westurner tools; mkdir -p $_SRC git clone ssh://git@github.com/westurner/tools cdw; e index.rst # ew index.rst
https://github.com/westurner/tools/blob/master/index.rst
https://raw.githubusercontent.com/westurner/tools/master/index.rst
* Output:
.. code:: bash
cd $_WRD # cdwrd; cdw git status; make <tab> # gitw status; makew <tab> make html singlehtml # make docs web ./_build/html/index.html # make open
make gh-pages # ghp-import -n -p ./_build/html/ -b gh-pages make push # gitw push <origin> <destbranch>
https://github.com/westurner/tools/blob/gh-pages/index.html
https://westurner.github.io/tools/
* RawGit:
dev/test: https://rawgit.com/westurner/tools/gh-pages/index.html
CDN: https://cdn.rawgit.com/westurner/tools/gh-pages/index.html
* Output: *ReadTheDocs*:
https://<projectname>.readthedocs.io/en/<version>/
https://read-the-docs.readthedocs.io/en/latest/
.. glossary::
Sphinx Builder A Sphinx Builder transforms :ref:`ReStructuredText` into various output forms:
* HTML * LaTeX * PDF * ePub * MOBI * JSON * OpenDocument (OpenOffice) * Office Open XML (MS Word)
See: `Sphinx Builders http://sphinx-doc.org/builders.html`_
Sphinx ReStructuredText Sphinx extends :ref:`ReStructuredText` with roles and directives which only work with Sphinx.
Sphinx Directive Sphinx extensions of :ref:`Docutils` :ref:`ReStructuredText` directives.
Most other ReStructuredText parsers do not support Sphinx directives.
.. code-block:: rest
.. toctree::
readme installation usage
See: `Sphinx Directives http://sphinx-doc.org/rest.html#directives`_
Sphinx Role Sphinx extensions of :ref:`Docutils` :ref:`RestructuredText` roles
Most other ReStructuredText parsers do not support Sphinx directives.
.. code-block:: rest
.. _anchor-name:
A link to :ref:`anchor <anchor-name>`.
```
On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet corbet@lwn.net wrote:
On Tue, 23 Apr 2019 15:01:32 +0200 Peter Zijlstra peterz@infradead.org 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