Migration to Sphinx

Migration to Sphinx

[Nicolas Dechesne]

hi there,

I wanted to update everyone with the outcome of our meeting today.
Mark Morton, Richard and I attended and discussed the Sphinx
conversion.

Overall we've reached an agreement that this is probably the best
tradeoff, and we want to go ahead. Richard will talk to the TSC of
course, for a final round of approval.

Here is the proposed plan of actions:

1. we will start a 'sphinx' branch in yocto-docs and bitbake (bitbake
DocBook manual is hosted in bitbake tree). This will be a development
branch we can all use for the initial conversion. Once we are 'done'
with the content and that all the documentation is migrated from
Docbook to Sphinx, this will be merged in the respective master
branches.
Note that we might rebase/squash the 'sphinx' branches from time to time.
2. Patches for the 'sphinx' branches should be sent/reviewed on this
list with [sphinx] in the email subject.
3. Mark, Richard and myself will maintain this branch initially.
4. We will setup a script to generate and push the HTML content every
time the branch is updated
5. Mark will investigate how to create our custom CSS theme, and will
make a first implementation.
6. The doc changes between master and dunfell are fairly minimal right
now, so assuming this goes well and is ready for 3.2, we will most
likely backport the sphinx based documentation for 3.1 (but not
previous releases).
7. We intend to continue to provide our legendary mega manual (we all
have it opened at least once in our browser!).

For now we are using the following wiki page to track this activity:
https://wiki.yoctoproject.org/wiki/Documentation_Sphinx

If you have any feedback, please let us know. We expect to get started
in the next week or so.

cheers
nico