- 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 On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <cor...@lwn.net> wrote: > On Tue, 23 Apr 2019 15:01:32 +0200 > Peter Zijlstra <pet...@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 >
_______________________________________________ dri-devel mailing list dri-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/dri-devel
