[ovs-dev] [RFC 0/5] Integrate Sphinx documentation generator

Stephen Finucane stephen at that.guru
Sat Oct 1 19:01:29 UTC 2016


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.

Stephen Finucane (5):
  Add initial sphinx configuration
  doc: Add a 'install-guide' section
  doc: Add a 'testing-guide' section
  doc: Add a 'contributor-guide' section
  doc: Convert README to rST

 Documentation/_build/.keep                         |   0
 Documentation/_static/.keep                        |   0
 Documentation/_templates/.keep                     |   0
 Documentation/conf.py                              | 338 +++++++++++++
 .../committer-grant-revocation.rst                 | 398 ++++++++++++++++
 .../committer-responsibilities.rst                 |  96 ++++
 Documentation/contributor-guide/index.rst          |  34 ++
 Documentation/index.rst                            |  44 ++
 Documentation/install-guide/dpdk.rst               | 405 ++++++++++++++++
 Documentation/install-guide/general.rst            | 524 +++++++++++++++++++++
 Documentation/install-guide/index.rst              |  34 ++
 Documentation/test-guide/code-analysis.rst         |  45 ++
 Documentation/test-guide/datapath.rst              | 138 ++++++
 Documentation/test-guide/dpdk.rst                  | 226 +++++++++
 Documentation/test-guide/index.rst                 |  45 ++
 Documentation/test-guide/oftest.rst                |  87 ++++
 Documentation/test-guide/ryu.rst                   |  62 +++
 Documentation/test-guide/travis.rst                |  64 +++
 Documentation/test-guide/unit.rst                  | 106 +++++
 INSTALL.md                                         |   4 +-
 Makefile.am                                        |   8 +-
 README.md                                          | 131 ------
 README.rst                                         | 115 +++++
 rhel/openvswitch-fedora.spec.in                    |   2 +-
 rhel/openvswitch.spec.in                           |   2 +-
 utilities/ovs-ctl.8                                |   2 +-
 26 files changed, 2773 insertions(+), 137 deletions(-)
 create mode 100644 Documentation/_build/.keep
 create mode 100644 Documentation/_static/.keep
 create mode 100644 Documentation/_templates/.keep
 create mode 100644 Documentation/conf.py
 create mode 100644 Documentation/contributor-guide/committer-grant-revocation.rst
 create mode 100644 Documentation/contributor-guide/committer-responsibilities.rst
 create mode 100644 Documentation/contributor-guide/index.rst
 create mode 100644 Documentation/index.rst
 create mode 100644 Documentation/install-guide/dpdk.rst
 create mode 100644 Documentation/install-guide/general.rst
 create mode 100644 Documentation/install-guide/index.rst
 create mode 100644 Documentation/test-guide/code-analysis.rst
 create mode 100644 Documentation/test-guide/datapath.rst
 create mode 100644 Documentation/test-guide/dpdk.rst
 create mode 100644 Documentation/test-guide/index.rst
 create mode 100644 Documentation/test-guide/oftest.rst
 create mode 100644 Documentation/test-guide/ryu.rst
 create mode 100644 Documentation/test-guide/travis.rst
 create mode 100644 Documentation/test-guide/unit.rst
 delete mode 100644 README.md
 create mode 100644 README.rst

-- 
2.7.4




More information about the dev mailing list