- 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/#docutilsI'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/trunkDocutils 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-sphinxdocSphinx 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