- Accessible, usable docs are worth something in ROI
- 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)
- 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)
- This says "Copyright 2016"? That's set in conf.py
I keep a tools doc in ReST:
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.
.. _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.
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@xxxxxxxxxx/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>`.
.. _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.
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@xxxxxxxxxx/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
* 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@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
_______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel
