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
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
