- 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: ```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. 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://g...@github.com/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>`. ``` 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 >
_______________________________________________ Openipmi-developer mailing list Openipmi-developer@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openipmi-developer
