[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <CACfEFw-viqBH7tDJ8t_um5erPFnRmzuztux86+3XR0+e=YcYYA@mail.gmail.com>
Date: Tue, 23 Apr 2019 13:13:54 -0400
From: Wes Turner <wes.turner@...il.com>
To: Jonathan Corbet <corbet@....net>
Cc: Peter Zijlstra <peterz@...radead.org>, Mike Snitzer <snitzer@...hat.com>,
Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
Linux Doc Mailing List <linux-doc@...r.kernel.org>, Mauro Carvalho Chehab <mchehab@...radead.org>,
Linux Kernel Mailing List <linux-kernel@...r.kernel.org>, Johannes Berg <johannes@...solutions.net>,
Kurt Schwemmer <kurt.schwemmer@...rosemi.com>, Logan Gunthorpe <logang@...tatee.com>,
Bjorn Helgaas <bhelgaas@...gle.com>, Alasdair Kergon <agk@...hat.com>, dm-devel@...hat.com,
Kishon Vijay Abraham I <kishon@...com>, Rob Herring <robh+dt@...nel.org>, Mark Rutland <mark.rutland@....com>,
Bartlomiej Zolnierkiewicz <b.zolnierkie@...sung.com>, David Airlie <airlied@...ux.ie>,
Daniel Vetter <daniel@...ll.ch>, Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
Maxime Ripard <maxime.ripard@...tlin.com>, Sean Paul <sean@...rly.run>,
Ning Sun <ning.sun@...el.com>, Ingo Molnar <mingo@...hat.com>, Will Deacon <will.deacon@....com>,
Alan Stern <stern@...land.harvard.edu>,
Andrea Parri <andrea.parri@...rulasolutions.com>, Boqun Feng <boqun.feng@...il.com>,
Nicholas Piggin <npiggin@...il.com>, David Howells <dhowells@...hat.com>,
Jade Alglave <j.alglave@....ac.uk>, Luc Maranget <luc.maranget@...ia.fr>,
"Paul E. McKenney" <paulmck@...ux.ibm.com>, Akira Yokosawa <akiyks@...il.com>,
Daniel Lustig <dlustig@...dia.com>, "David S. Miller" <davem@...emloft.net>,
Andreas Färber <afaerber@...e.de>,
Manivannan Sadhasivam <manivannan.sadhasivam@...aro.org>, Cornelia Huck <cohuck@...hat.com>,
Farhan Ali <alifm@...ux.ibm.com>, Eric Farman <farman@...ux.ibm.com>,
Halil Pasic <pasic@...ux.ibm.com>, Martin Schwidefsky <schwidefsky@...ibm.com>,
Heiko Carstens <heiko.carstens@...ibm.com>, Harry Wei <harryxiyou@...il.com>,
Alex Shi <alex.shi@...ux.alibaba.com>, Jerry Hoemann <jerry.hoemann@....com>,
Wim Van Sebroeck <wim@...ux-watchdog.org>, Guenter Roeck <linux@...ck-us.net>,
Thomas Gleixner <tglx@...utronix.de>, Borislav Petkov <bp@...en8.de>, "H. Peter Anvin" <hpa@...or.com>, x86@...nel.org,
Russell King <linux@...linux.org.uk>, Tony Luck <tony.luck@...el.com>,
Fenghua Yu <fenghua.yu@...el.com>,
"James E.J. Bottomley" <James.Bottomley@...senpartnership.com>, Helge Deller <deller@....de>,
Yoshinori Sato <ysato@...rs.sourceforge.jp>, Rich Felker <dalias@...c.org>,
Guan Xuetao <gxt@....edu.cn>, Jens Axboe <axboe@...nel.dk>,
Greg Kroah-Hartman <gregkh@...uxfoundation.org>, "Rafael J. Wysocki" <rafael@...nel.org>,
Arnd Bergmann <arnd@...db.de>, Matt Mackall <mpm@...enic.com>,
Herbert Xu <herbert@...dor.apana.org.au>, Corey Minyard <minyard@....org>,
Sumit Semwal <sumit.semwal@...aro.org>, Linus Walleij <linus.walleij@...aro.org>,
Bartosz Golaszewski <bgolaszewski@...libre.com>, Darren Hart <dvhart@...radead.org>,
Andy Shevchenko <andy@...radead.org>, Stuart Hayes <stuart.w.hayes@...il.com>,
Jaroslav Kysela <perex@...ex.cz>, Alex Williamson <alex.williamson@...hat.com>,
Kirti Wankhede <kwankhede@...dia.com>, Christoph Hellwig <hch@....de>,
Marek Szyprowski <m.szyprowski@...sung.com>, Robin Murphy <robin.murphy@....com>,
Steffen Klassert <steffen.klassert@...unet.com>, Kees Cook <keescook@...omium.org>,
Emese Revfy <re.emese@...il.com>, James Morris <jmorris@...ei.org>,
"Serge E. Hallyn" <serge@...lyn.com>, linux-wireless@...r.kernel.org,
linux-pci@...r.kernel.org, devicetree@...r.kernel.org,
dri-devel@...ts.freedesktop.org, linux-fbdev@...r.kernel.org,
tboot-devel@...ts.sourceforge.net, linux-arch@...r.kernel.org,
netdev@...r.kernel.org, linux-arm-kernel@...ts.infradead.org,
linux-s390@...r.kernel.org, kvm@...r.kernel.org,
linux-watchdog@...r.kernel.org, linux-ia64@...r.kernel.org,
linux-parisc@...r.kernel.org, linux-sh@...r.kernel.org,
sparclinux@...r.kernel.org, linux-block@...r.kernel.org,
linux-crypto@...r.kernel.org, openipmi-developer@...ts.sourceforge.net,
linaro-mm-sig@...ts.linaro.org, linux-gpio@...r.kernel.org,
platform-driver-x86@...r.kernel.org, iommu@...ts.linux-foundation.org,
linux-mm <linux-mm@...ck.org>, Kernel Hardening <kernel-hardening@...ts.openwall.com>,
linux-security-module@...r.kernel.org
Subject: Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files
to *.rst
- 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://git@...hub.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 <corbet@....net> wrote:
> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz@...radead.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
>
Content of type "text/html" skipped
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
