On Wed, Oct 05, 2016 at 10:05:50AM +0000, Stephen Finucane wrote: > 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.
OK. > 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. Sounds good to me. > >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. For me, at least, that's something of a separate issue, and I agree that it should be deferred. > >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. I'm happy with the idea. > 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) OK. I can help with the md->rst conversion. > 2) Integrate Sphinx > > Move all documents except traditional top-level docs (README, CodingStyle > etc.) to 'Documentation' That's probably overdue anyway. > 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). OK. > 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? We probably want to have separate guides for OVS and for OVN, at least for installation and usage. > 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. I can help with some MD->RST. You mentioned that you've already done it for about half the docs and hadn't posted all of those. Thanks a lot for taking this on! It's something I've thought of before (I was thinking of a DocBook or Texinfo route, although I wasn't really satisfied with either of those; Sphinx seems fine), but I've never actually taken it on. _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
