[ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator
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
>> 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
>> over as you add more and more documents and see the need for thing
>> 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
>> 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
>> 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
> 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  with a
consistent style. For an example of what's possible here, look at the
OpenStack docs , the Nova developer docs  and the Python docs .
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 , but this is totally optional and should be done at
> 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'  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  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.
More information about the dev