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