<div dir="ltr"><div dir="ltr">- Accessible, usable docs are worth something in ROI - <a href="https://www.writethedocs.org/">https://www.writethedocs.org/</a> - <a href="https://read-the-docs.readthedocs.io/en/latest/">https://read-the-docs.readthedocs.io/en/latest/</a> - <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> - 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) - <a href="https://github.com/yoloseem/awesome-sphinxdoc">https://github.com/yoloseem/awesome-sphinxdoc</a> - 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) - <a href="https://kernel.readthedocs.io/en/latest/kernel-documentation.html">https://kernel.readthedocs.io/en/latest/kernel-documentation.html</a> - This says "Copyright 2016"? That's set in conf.py I keep a tools doc in ReST: - <a href="https://westurner.github.io/tools/#sphinx">https://westurner.github.io/tools/#sphinx</a> - <a href="https://westurner.github.io/tools/#docutils">https://westurner.github.io/tools/#docutils</a> I'll just CC those sections here wrapped in a Markdown fenced code block ```rst .. index:: Docutils .. _docutils: Docutils ~~~~~~~~~~~~~~~~~~~ | Homepage: <a href="http://docutils.sourceforge.net">http://docutils.sourceforge.net</a> | PyPI: <a href="https://pypi.python.org/pypi/docutils">https://pypi.python.org/pypi/docutils</a> | Docs: <a href="http://docutils.sourceforge.net/docs/">http://docutils.sourceforge.net/docs/</a> | Docs: <a href="http://docutils.sourceforge.net/rst.html">http://docutils.sourceforge.net/rst.html</a> | Docs: <a href="http://docutils.sourceforge.net/docs/ref/doctree.html">http://docutils.sourceforge.net/docs/ref/doctree.html</a> | Docs: <a href="https://docutils.readthedocs.io/en/sphinx-docs/">https://docutils.readthedocs.io/en/sphinx-docs/</a> | 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> | Src: svn <a href="http://svn.code.sf.net/p/docutils/code/trunk">http://svn.code.sf.net/p/docutils/code/trunk</a> 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: `<<a href="https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)">https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)</a>>`_ | Homepage: <a href="https://pypi.python.org/pypi/Sphinx">https://pypi.python.org/pypi/Sphinx</a> | Src: git <a href="https://github.com/sphinx-doc/sphinx">https://github.com/sphinx-doc/sphinx</a> | Pypi: <a href="https://pypi.python.org/pypi/Sphinx">https://pypi.python.org/pypi/Sphinx</a> | Docs: <a href="http://sphinx-doc.org/contents.html">http://sphinx-doc.org/contents.html</a> | Docs: <a href="http://sphinx-doc.org/markup/code.html">http://sphinx-doc.org/markup/code.html</a> | 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> | Docs: <a href="http://pygments.org/docs/lexers/">http://pygments.org/docs/lexers/</a> | Docs: <a href="http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html">http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html</a> | Docs: <a href="https://github.com/yoloseem/awesome-sphinxdoc">https://github.com/yoloseem/awesome-sphinxdoc</a> 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 <a href="https://www.kernel.org/doc/html/latest/">https://www.kernel.org/doc/html/latest/</a> - <a href="https://github.com/torvalds/linux/blob/master/Documentation/conf.py">https://github.com/torvalds/linux/blob/master/Documentation/conf.py</a> - <a href="https://github.com/torvalds/linux/blob/master/Documentation/Makefile">https://github.com/torvalds/linux/blob/master/Documentation/Makefile</a> - <a href="https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/index.rst">https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/index.rst</a> - <a href="https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/sphinx.rst">https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/sphinx.rst</a> - <a href="https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/kernel-doc.rst">https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/kernel-doc.rst</a> - <a href="https://www.kernel.org/doc/html/latest/">https://www.kernel.org/doc/html/latest/</a> - <a href="https://www.kernel.org/doc/html/latest/doc-guide/">https://www.kernel.org/doc/html/latest/doc-guide/</a> - <a href="https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install">https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install</a> - <a href="https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments">https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments</a> </div></div> <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: </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 Peter Zijlstra <<a href="mailto:peterz@infradead.org" target="_blank">peterz@infradead.org</a>> 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 </blockquote></div>