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? In particular, it would be
good to make sure that the manpages make it into the output.
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.
--8<--------------------------cut here-------------------------->8--
diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index d709e77..1d1f9ce 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -1,6 +1,25 @@
docs += \
- Documentation/committer-responsibilities.md \
+ Documentation/OVSDB-replication.md \
+ Documentation/_build/.keep \
+ Documentation/_static/.keep \
+ Documentation/_templates/.keep \
Documentation/committer-grant-revocation.md \
+ Documentation/committer-responsibilities.md \
+ Documentation/conf.py \
+ Documentation/contributor-guide/committer-grant-revocation.rst \
+ Documentation/contributor-guide/committer-responsibilities.rst \
+ Documentation/contributor-guide/index.rst \
Documentation/group-selection-method-property.txt \
- Documentation/OVSDB-replication.md \
- Documentation/release-process.md
+ Documentation/index.rst \
+ Documentation/install-guide/dpdk.rst \
+ Documentation/install-guide/general.rst \
+ Documentation/install-guide/index.rst \
+ Documentation/release-process.md \
+ Documentation/test-guide/code-analysis.rst \
+ Documentation/test-guide/datapath.rst \
+ Documentation/test-guide/dpdk.rst \
+ Documentation/test-guide/index.rst \
+ Documentation/test-guide/oftest.rst \
+ Documentation/test-guide/ryu.rst \
+ Documentation/test-guide/travis.rst \
+ Documentation/test-guide/unit.rst
diff --git a/Documentation/test-guide/unit.rst
b/Documentation/test-guide/unit.rst
index 153352b..66aa469 100644
--- a/Documentation/test-guide/unit.rst
+++ b/Documentation/test-guide/unit.rst
@@ -1,5 +1,4 @@
..
-
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
diff --git a/Makefile.am b/Makefile.am
index e05b1b1..b0cfa9e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -420,9 +420,9 @@ if LINUX_ENABLED
cd datapath/linux && $(MAKE) modules_install
endif
-SPHINXSOURCEDIR = Documentation
+SPHINXSOURCEDIR = $(srcdir)/Documentation
SPHINXBUILD = sphinx-build
-SPHINXBUILDDIR = $(SPHINXSOURCEDIR)/_build
+SPHINXBUILDDIR = $(builddir)/Documentation/_build
dist-docs:
VERSION=$(VERSION) MAKE='$(MAKE)' $(srcdir)/build-aux/dist-docs
$(srcdir) $(docs)
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
