[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.



[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
[6] http://docutils.sourceforge.net/docs/user/tools.html#rst2html-py

More information about the dev mailing list