<div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div>- Accessible, usable docs are worth something in ROI</div><div> - <a href="https://www.writethedocs.org/">https://www.writethedocs.org/</a></div><div> - <a href="https://read-the-docs.readthedocs.io/en/latest/">https://read-the-docs.readthedocs.io/en/latest/</a></div><div> - <a href="https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800">https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800</a></div><div> - 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)</div><div><br></div><div>- <a href="https://github.com/yoloseem/awesome-sphinxdoc">https://github.com/yoloseem/awesome-sphinxdoc</a></div><div> - There are various Sphinx extensions for optionally including generated API docs for various languages</div><div> - 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)<br></div><div><br></div><div>- <a href="https://kernel.readthedocs.io/en/latest/kernel-documentation.html">https://kernel.readthedocs.io/en/latest/kernel-documentation.html</a></div><div> - This says "Copyright 2016"? That's set in conf.py</div><div><br></div><div>I keep a tools doc in ReST:</div><div>- <a href="https://westurner.github.io/tools/#sphinx">https://westurner.github.io/tools/#sphinx</a></div><div>- <a href="https://westurner.github.io/tools/#docutils">https://westurner.github.io/tools/#docutils</a></div><div><br></div><div>I'll just CC those sections here:</div><div><br></div><div>```rst<br></div><div><br></div><div>.. index:: Docutils<br>.. _docutils:<br><br>Docutils<br>~~~~~~~~~~~~~~~~~~~<br>| Homepage: <a href="http://docutils.sourceforge.net">http://docutils.sourceforge.net</a><br>| PyPI: <a href="https://pypi.python.org/pypi/docutils">https://pypi.python.org/pypi/docutils</a><br>| Docs: <a href="http://docutils.sourceforge.net/docs/">http://docutils.sourceforge.net/docs/</a><br>| Docs: <a href="http://docutils.sourceforge.net/rst.html">http://docutils.sourceforge.net/rst.html</a><br>| Docs: <a href="http://docutils.sourceforge.net/docs/ref/doctree.html">http://docutils.sourceforge.net/docs/ref/doctree.html</a><br>| Docs: <a href="https://docutils.readthedocs.io/en/sphinx-docs/">https://docutils.readthedocs.io/en/sphinx-docs/</a><br>| Docs: <a href="https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html">https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html</a><br>| Src: svn <a href="http://svn.code.sf.net/p/docutils/code/trunk">http://svn.code.sf.net/p/docutils/code/trunk</a><br><br>Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`<br>lightweight markup language into a doctree (~DOM)<br>which can be serialized into<br>HTML, ePub, MOBI, LaTeX, man pages,<br>Open Document files,<br>XML, JSON, and a number of other formats.</div><div><br></div><div>.. index:: Sphinx<br>.. _sphinx:<br><br>Sphinx<br>~~~~~~~~~~~~~~~~~<br>| Wikipedia: `<<a href="https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)">https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)</a>>`_<br>| Homepage: <a href="https://pypi.python.org/pypi/Sphinx">https://pypi.python.org/pypi/Sphinx</a><br>| Src: git <a href="https://github.com/sphinx-doc/sphinx">https://github.com/sphinx-doc/sphinx</a><br>| Pypi: <a href="https://pypi.python.org/pypi/Sphinx">https://pypi.python.org/pypi/Sphinx</a><br>| Docs: <a href="http://sphinx-doc.org/contents.html">http://sphinx-doc.org/contents.html</a><br>| Docs: <a href="http://sphinx-doc.org/markup/code.html">http://sphinx-doc.org/markup/code.html</a><br>| Docs: <a href="http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role">http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role</a><br>| Docs: <a href="http://pygments.org/docs/lexers/">http://pygments.org/docs/lexers/</a><br>| Docs: <a href="http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html">http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html</a><br>| Docs: <a href="https://github.com/yoloseem/awesome-sphinxdoc">https://github.com/yoloseem/awesome-sphinxdoc</a><br><br><br>Sphinx is a tool for working with<br>:ref:`ReStructuredText` documentation trees<br>and rendering them into HTML, PDF, LaTeX, ePub,<br>and a number of other formats.<br><br>Sphinx extends :ref:`Docutils` with a number of useful markup behaviors<br>which are not supported by other ReStructuredText parsers.<br><br>Most other ReStructuredText parsers do not support Sphinx directives;<br>so, for example,<br><br>* GitHub and BitBucket do not support Sphinx but do support ReStructuredText<br> so ``README.rst`` containing Sphinx tags renders in plaintext or raises errors.<br><br> For example, the index page of this<br> :ref:`Sphinx` documentation set is generated from<br> a file named ``index.rst`` that referenced by ``docs/conf.py``,<br> which is utilized by ``sphinx-build`` in the ``Makefile``.<br><br> * Input:<br><br> .. code:: bash<br><br> _indexrst="$WORKON_HOME/src/westurner/tools/index.rst"<br> e $_indexrst<br><br> # with westurner/dotfiles.venv<br> mkvirtualenv westurner<br> we westurner tools; mkdir -p $_SRC<br> git clone ssh://<a href="http://git@github.com/westurner/tools">git@github.com/westurner/tools</a><br> cdw; e index.rst # ew index.rst<br><br> <a href="https://github.com/westurner/tools/blob/master/index.rst">https://github.com/westurner/tools/blob/master/index.rst</a><br><br> <a href="https://raw.githubusercontent.com/westurner/tools/master/index.rst">https://raw.githubusercontent.com/westurner/tools/master/index.rst</a><br><br><br><br> * Output:<br><br> .. code:: bash<br><br> cd $_WRD # cdwrd; cdw<br> git status; make <tab> # gitw status; makew <tab><br> make html singlehtml # make docs<br> web ./_build/html/index.html # make open<br><br> make gh-pages # ghp-import -n -p ./_build/html/ -b gh-pages<br> make push # gitw push <origin> <destbranch><br><br> <a href="https://github.com/westurner/tools/blob/gh-pages/index.html">https://github.com/westurner/tools/blob/gh-pages/index.html</a><br><br> <a href="https://westurner.github.io/tools/">https://westurner.github.io/tools/</a><br><br><br> * RawGit:<br><br> dev/test: <a href="https://rawgit.com/westurner/tools/gh-pages/index.html">https://rawgit.com/westurner/tools/gh-pages/index.html</a><br><br> CDN: <a href="https://cdn.rawgit.com/westurner/tools/gh-pages/index.html">https://cdn.rawgit.com/westurner/tools/gh-pages/index.html</a><br><br> * Output: *ReadTheDocs*:<br><br> https://<projectname>.<a href="http://readthedocs.io/en/">readthedocs.io/en/</a><version>/<br><br> <a href="https://read-the-docs.readthedocs.io/en/latest/">https://read-the-docs.readthedocs.io/en/latest/</a><br><br><br>.. glossary::<br><br> Sphinx Builder<br> A Sphinx Builder transforms :ref:`ReStructuredText` into various<br> output forms:<br><br> * HTML<br> * LaTeX<br> * PDF<br> * ePub<br> * MOBI<br> * JSON<br> * OpenDocument (OpenOffice)<br> * Office Open XML (MS Word)<br><br> See: `Sphinx Builders <<a href="http://sphinx-doc.org/builders.html">http://sphinx-doc.org/builders.html</a>>`_<br><br> Sphinx ReStructuredText<br> Sphinx extends :ref:`ReStructuredText` with roles and directives<br> which only work with Sphinx.<br><br> Sphinx Directive<br> Sphinx extensions of :ref:`Docutils` :ref:`ReStructuredText` directives.<br><br> Most other ReStructuredText parsers do not support Sphinx directives.<br><br> .. code-block:: rest<br><br> .. toctree::<br><br> readme<br> installation<br> usage<br><br> See: `Sphinx Directives <<a href="http://sphinx-doc.org/rest.html#directives">http://sphinx-doc.org/rest.html#directives</a>>`_<br><br> Sphinx Role<br> Sphinx extensions of :ref:`Docutils` :ref:`RestructuredText` roles<br><br> Most other ReStructuredText parsers do not support Sphinx directives.<br><br> .. code-block:: rest<br><br> .. _anchor-name:<br><br> A link to :ref:`anchor <anchor-name>`.<br></div><div><br></div><div>```<br></div></div></div></div></div></div></div></div></div></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <<a href="mailto:corbet@lwn.net">corbet@lwn.net</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Tue, 23 Apr 2019 15:01:32 +0200<br>
Peter Zijlstra <<a href="mailto:peterz@infradead.org" target="_blank">peterz@infradead.org</a>> wrote:<br>
<br>
> But yes, I have 0 motivation to learn or abide by rst. It simply doesn't<br>
> give me anything in return. There is no upside, only worse text files :/<br>
<br>
So I believe it gives even you one thing in return: documentation that is<br>
more accessible for both readers and authors. More readable docs should<br>
lead to more educated developers who understand the code better. More<br>
writable docs will bring more people in to help to improve them. The<br>
former effect has been reported in the GPU community, where they say that<br>
the quality of submissions has improved along with the docs. The latter<br>
can be observed in the increased number of people working on the docs<br>
overall, something that Linus noted in the 5.1-rc1 announcement.<br>
<br>
Hopefully that's worth something :)<br>
<br>
Thanks,<br>
<br>
jon<br>
</blockquote></div>