hi,

On Wed, Apr 15, 2020 at 12:19 PM Richard Purdie <
richard.purdie@linuxfoundation.org> wrote:

> Since Robert was talking about future docs wide changes, I wanted to
> put an idea out there. Its something a few of us have talked a little
> about. At this point it is an idea, not a decision and something we're
> thinking we need to explore and evaluate.
>
> Basically, the thought is whether to move from docbook to sphinx.
>

Good timing. I have been tossing around this idea... As much as I love
using and reading the YP docs/manual, I know that maintaining and updating
the documentation 'sources' is rather difficult.


> Other projects like the kernel have switched and it could assist some
> of our website/publishing challenges. It might also be easier for
> people to contribute to and there are wider and more modern tools
> supporting that format.
>

Right, and they claimed in https://lwn.net/Articles/692704/:
"if the documentation can be written in plain text rather than DocBook XML,
it's more likely to be written in the first place."

I have spent no more than a couple of hours on it, trying to understand why
the kernel moved and how Sphinx works. The outcome is really
interesting...

I use a conversion tool for DocBook .xml to Sphinx/ReST file format
(pandoc). Of course there are conversion gothas.. but the documentation
source code becomes much easier.

See:
https://people.linaro.org/~nicolas.dechesne/yp-docs/_sources/ref-manual/ref-release-process.xml.rst.txt
vs
http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/documentation/ref-manual/ref-release-process.xml

Or even for the variable glossary (sphinx has builtin support for that):
https://people.linaro.org/~nicolas.dechesne/yp-docs/_sources/ref-manual/ref-variables.xml.rst

vs
http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/documentation/ref-manual/ref-variables.xml

I have picked the same theme as the Linux kernel documentation, but of
course, the theme is just HTML and CSS, so it's entirely customizable.

For now, only 3 manuals were converted, the html output looks like that:
https://people.linaro.org/~nicolas.dechesne/yp-docs/

I have made a couple of patches to show how to get there:
https://git.linaro.org/people/nicolas.dechesne/poky.git/log/?h=sphinx

It was straightforward to install anything i needed:
sudo apt install pandoc
pip3 install sphinx
# to use the non default theme
pip3 install sphinx_rtd_theme

then it's just:
make html


> It'd be a big change, particularly if we consider we may need to
> convert previous releases of the docs as well as the current version.
> That said, if we were going to do this, the time could be now...
>

The intent is just to show where this could lead us. We need to ensure that
it will not affect the quality of our documentation, which is obviously one
of the project's gems!


>
> Cheers,
>
> Richard
>
>
>
>
>
>