[ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator
Stephen Finucane
stephen at that.guru
Wed Oct 5 10:05:50 UTC 2016
On 2016-10-04 22:01, Ben Pfaff wrote:
> On Sat, Oct 01, 2016 at 08:01:29PM +0100, Stephen Finucane wrote:
>> Since the move to GitHub, OVS has increasingly used Markdown for all
>> of
>> its documentation. This seems like a natural fit, given Markdown's low
>> overhead and support in the GitHub web UI. However, Markdown is a
>> documentation format, not a documentation system, and it starts to
>> fall
>> over as you add more and more documents and see the need for thing
>> like
>> cross-referencing, or insertion of partial documents into other docs.
>>
>> I'd like to propose integrating the Sphinx documentation tool into the
>> OVS documentation. This would mean converting most or all of the
>> documentation to reStructuredText, but it would bring significant
>> advantages including:
>>
>> * native cross-referencing
>> * multiple output formats (including pretty HTML)
>> * automatic indexing/searching of docs
>> * hierarchial structuring of the docs
>> * DRY documents, through inclusion of partial docs in multiple files
>> * ...
>>
>> I chose rST+Sphinx due to the overwhelming popularity of the tool
>> within other open source communities like the Linux kernel and
>> OpenStack, which have all migrated documentation from other tools
>> (DocBook, mostly) in recent times.
>>
>> Documents located in the top-level directory should also be converted
>> to rST to be consistent, but these should not include any Sphinx
>> extensions to ensure that these continue to be readable on GitHub.
>>
>> I've included some patches that show the kind of changes that would be
>> necessary. I've actually converted far more of the docs (~40%?) at
>> this
>> point, but I'd like to gauge interest before continuing with the
>> remainder. I'd also appreciate help from folks who would take a stab
>> at
>> coverting docs so I don't have to do it all by myself.
>>
>> Feel free to direct any questions at me.
>
> This seems quite nice. I played with it for a few minutes and looked
> at
> the generated HTML output, which is nicer than the current "make
> dist-docs" output.
>
> I assume that, if this were to be fully converted, then the generated
> webpage would replace "make dist-docs" and point to all the
> documentation that that currently outputs?
Yes, that would be the intention. We could keep the 'dist-docs' target
to build offline copies of the documentation but it would eventually use
sphinx instead of the 'dist-docs' script.
I would also like to provide a custom stylesheet/Sphinx theme so we
could display docs on the current documentation page [1] with a
consistent style. For an example of what's possible here, look at the
OpenStack docs [2], the Nova developer docs [3] and the Python docs [4].
Despite varying appearances, all are generated using Sphinx.
> In particular, it would be
> good to make sure that the manpages make it into the output.
manpages would be included. We may wish to rewrite these in reST like
OpenStack do [5], but this is totally optional and should be done at
another time.
> I had to fold in the appended patch to get "make" to pass, to support
> out-of-tree builds, and to make the license disappear from the "unit
> tests" page.
Yeah, the Makefile was a (poor) first pass, so thanks for the patch. The
proper version will be actually tested.
Assuming we're good with the idea, here's my current POA.
1) Convert all docs in-place to reStructuredText
Update the 'dist-docs' script to use 'rst2html' [6] for '*.rst'
files. The documentation output will remain essentially the same for
now. This will be a slog, but it's rather trivial to review (cursory
visual inspection) and is necessary for (2)
2) Integrate Sphinx
Move all documents except traditional top-level docs (README,
CodingStyle etc.) to 'Documentation' and build with sphinx instead of
'rst2html'. The openvswitch.org docs page [1] will start using the
sphinx output. Files would retain their existing names and structure
meaning the docs index page will simply be a dumb list of these files
(like today, really).
3) Rework docs into a series of guides
I see the following guides as being helpful
- Installation guide
- Usage guide
- Contributor guide
I had a 'testing-guide', but this makes more sense split between the
middle two. Any other guides?
This would be three separate series so I don't have to do everything at
once. I'd also welcome assistance from anyone who wants to take the
chance to rework some aspect of the docs.
Cheers,
Stephen
[1] http://openvswitch.org/support/dist-docs/
[2] http://docs.openstack.org/admin-guide/compute-cpu-topologies.html
[3] http://docs.openstack.org/developer/nova/testing/libvirt-numa.html
[4] https://docs.python.org/3/library/mailbox.html
[5]
https://github.com/openstack/python-openstackclient/blob/3.2.0/doc/source/man/openstack.rst
[6] http://docutils.sourceforge.net/docs/user/tools.html#rst2html-py
More information about the dev
mailing list