Firstly, yay for alliteration. Secondly, sorry for this taking so long:
I must have respun this a dozen times trying to find the right way to
divide the docs into sections before settling Django's approach.
Thirdly, as y'all are aware, any and all documentation in Open vSwitch
was recently moved from Markdown to reStructuredText with the
intention of allowing Open vSwitch to use Sphinx. That refactor is now
complete, meaning it's time to Sphinx things up (sorry).
This series is the first in a number of planned series that rework and
expand the OVS documentation. This particular series aims to achieve
the following:
* Configure the basics required for Sphinx documentation generation
* Create a number of document sections and move all documents, with
the exception of some top-level files, into at least one of these
sections
* Update or remove references to any doc files which have been moved
Any significant refactoring of documentation has been left for future
series, though TODOs are included to remind people to do this. I plan
to follow-up this series with the following:
* A refactor of existing documents, moving content from one section to
another if it makes more sense. The (generally excellent, but
somewhat convoluted) DPDK-advanced guide is first on my radar.
* Adding further documentation to the '/topics' section, based on a
variety of blog posts and mailing list posts I've collected. A
change to the patch acceptance criteria could help in the long term
(think: don't add a new feature until how it works is explained in
the docs)?
* Other random oddities
Some other random thoughts:
* I have taken ownership of the 'openvswitch' project on ReadTheDocs
(openvswitch.readthedocs.io) to reserve the name and configure the
instance. I can transfer this once we're up and running and a
long-term maintainer is identified (I'd be interested)
* Someone needs to sync with both the ReadTheDocs folks and the
sysadmin in charge of 'openvswitch.org' to get a CNAME record added
for 'docs.openvswitch.org'
* We really needs a prettier theme, but I wasn't able to find one
better than what I've used
* Sphinx will not build if invalid syntax is used. As a result,
building docs should be part of the pre-merge workflow, if OVS has
such a thing. For example, a recent change to IntegrationGuide
contained invalid links that had to be fixed before merge
* I realise that packagers might miss not being able to include docs
like FAQ in their tarball, but realistically who reads documentation
like this? I've gone with the approach that, README aside, docs
should either be on docs.openvswitch.org or in a man page. Hopefully
you agree.
Stephen Finucane (14):
trivial: Don't mix tabs and spaces in ovs-sim
doc: Don't format emails as code
doc: Convert AUTHORS to rST
Add initial sphinx configuration
doc: Create directory structure
doc: Populate 'ref' section
doc: Populate 'internals' section
doc: Populate 'install', 'howto' sections
doc: Further populate the 'howto' section
doc: Populate 'topics' section
doc: Populate 'tutorials' section
doc: Move WHY-OVS
doc: Populate 'faq' section
doc: Remove documentation from distdoc target
.gitignore | 1 +
AUTHORS | 496 -----
AUTHORS.rst | 531 +++++
CONTRIBUTING.rst | 422 +---
Documentation/_static/logo.png | Bin 0 -> 13341 bytes
Documentation/automake.mk | 93 +-
Documentation/conf.py | 338 ++++
Documentation/contents.rst | 42 +
Documentation/faq/configuration.rst | 240 +++
Documentation/faq/contributing.rst | 75 +
Documentation/faq/design.rst | 110 +
Documentation/faq/general.rst | 132 ++
Documentation/faq/index.rst | 43 +
Documentation/faq/issues.rst | 416 ++++
Documentation/faq/openflow.rst | 537 +++++
Documentation/faq/qos.rst | 169 ++
Documentation/faq/releases.rst | 270 +++
Documentation/faq/terminology.rst | 37 +
Documentation/faq/vlan.rst | 282 +++
Documentation/faq/vxlan.rst | 53 +
.../howto/docker.rst | 13 +-
Documentation/howto/index.rst | 48 +
INSTALL.KVM.rst => Documentation/howto/kvm.rst | 15 +-
.../howto/libvirt.rst | 11 +-
README-lisp.rst => Documentation/howto/lisp.rst | 0
.../howto/native-tunneling.rst | 0
.../howto/openstack-containers.rst | 10 +-
.../howto/selinux.rst | 8 +-
INSTALL.SSL.rst => Documentation/howto/ssl.rst | 4 +-
.../howto/vtep.rst | 17 +-
Documentation/index.rst | 93 +
Documentation/internals/authors.rst | 24 +
.../internals/bugs.rst | 2 +-
.../{ => internals}/committer-grant-revocation.rst | 22 +-
.../{ => internals}/committer-responsibilities.rst | 8 +-
.../contributing/coding-style-windows.rst | 8 +-
.../internals/contributing/coding-style.rst | 2 +-
.../internals/contributing/documentation-style.rst | 8 +-
Documentation/internals/contributing/index.rst | 36 +
.../internals/contributing/submitting-patches.rst | 444 +++++
Documentation/internals/index.rst | 44 +
Documentation/internals/mailing-lists.rst | 96 +
Documentation/internals/maintainers.rst | 24 +
Documentation/{ => internals}/release-process.rst | 0
.../internals/security.rst | 36 +-
Documentation/intro/index.rst | 36 +
.../intro/install/bash-completion.rst | 0
.../intro/install/debian.rst | 16 +-
.../intro/install/dpdk-advanced.rst | 23 +-
.../intro/install/dpdk.rst | 54 +-
.../intro/install/fedora.rst | 19 +-
.../intro/install/general.rst | 35 +-
Documentation/intro/install/index.rst | 67 +
.../intro/install/netbsd.rst | 7 +-
.../intro/install/rhel.rst | 38 +-
.../intro/install/userspace.rst | 14 +-
.../intro/install/windows.rst | 3 +-
.../intro/install/xenserver.rst | 12 +-
WHY-OVS.rst => Documentation/intro/why-ovs.rst | 4 +-
Documentation/ref/index.rst | 175 ++
.../topics/bonding.rst | 38 +-
.../topics/datapath.rst | 0
DESIGN.rst => Documentation/topics/design.rst | 0
Documentation/topics/dpdk.rst | 28 +
.../topics/high-availability.rst | 0
Documentation/topics/index.rst | 49 +
.../topics/integration.rst | 49 +-
OPENFLOW.rst => Documentation/topics/openflow.rst | 28 +-
.../ovsdb-replication.rst} | 0
PORTING.rst => Documentation/topics/porting.rst | 5 +-
.../DESIGN.rst => Documentation/topics/windows.rst | 0
Documentation/tutorials/index.rst | 43 +
.../tutorials/ovn-basics.rst | 9 +-
.../tutorials/ovs-advanced.rst | 10 +-
FAQ.rst | 2093 --------------------
Makefile.am | 36 +-
README.rst | 36 +-
build-aux/dist-docs | 50 +-
datapath-windows/automake.mk | 2 -
datapath/Modules.mk | 3 -
debian/automake.mk | 6 +-
debian/openvswitch-common.docs | 3 -
debian/rules.modules | 2 +-
include/openvswitch/ofp-actions.h | 4 +-
include/openvswitch/ofp-util.h | 4 +-
lib/dpif.h | 5 +-
lib/mac-learning.c | 6 +-
lib/mac-learning.h | 4 +-
lib/netdev.h | 2 +-
lib/ofp-util.c | 2 +-
ofproto/connmgr.c | 2 +-
ofproto/ofproto-tnl-unixctl.man | 3 +-
ovn/automake.mk | 4 +-
ovn/controller/pinctrl.c | 3 +-
ovn/ovn-architecture.7.xml | 4 +-
rhel/openvswitch-fedora.spec.in | 3 +-
rhel/openvswitch.spec.in | 3 +-
tests/ovs-ofctl.at | 2 +-
tests/run-oftest | 2 +-
tests/run-ryu | 2 +-
third-party/automake.mk | 5 +-
tutorial/automake.mk | 3 -
tutorial/ovn/env1/setup.sh | 2 +-
tutorial/ovn/env6/setup.sh | 2 +-
tutorial/ovs-sandbox | 2 +-
utilities/automake.mk | 2 -
utilities/ovs-ctl.8 | 3 +-
utilities/ovs-dev.py | 2 +-
utilities/ovs-ofctl.8.in | 2 +-
utilities/ovs-sim.1.xml | 6 +-
utilities/ovs-sim.in | 104 +-
utilities/ovs-vsctl.8.in | 6 +-
vswitchd/automake.mk | 1 -
vswitchd/ovs-vswitchd.8.in | 10 +-
vtep/automake.mk | 1 -
vtep/vtep-ctl.8.in | 6 +-
xenserver/etc_init.d_openvswitch | 18 +-
117 files changed, 4950 insertions(+), 3533 deletions(-)
delete mode 100644 AUTHORS
create mode 100644 AUTHORS.rst
create mode 100644 Documentation/_static/logo.png
create mode 100644 Documentation/conf.py
create mode 100644 Documentation/contents.rst
create mode 100644 Documentation/faq/configuration.rst
create mode 100644 Documentation/faq/contributing.rst
create mode 100644 Documentation/faq/design.rst
create mode 100644 Documentation/faq/general.rst
create mode 100644 Documentation/faq/index.rst
create mode 100644 Documentation/faq/issues.rst
create mode 100644 Documentation/faq/openflow.rst
create mode 100644 Documentation/faq/qos.rst
create mode 100644 Documentation/faq/releases.rst
create mode 100644 Documentation/faq/terminology.rst
create mode 100644 Documentation/faq/vlan.rst
create mode 100644 Documentation/faq/vxlan.rst
rename INSTALL.Docker.rst => Documentation/howto/docker.rst (96%)
create mode 100644 Documentation/howto/index.rst
rename INSTALL.KVM.rst => Documentation/howto/kvm.rst (86%)
rename INSTALL.Libvirt.rst => Documentation/howto/libvirt.rst (87%)
rename README-lisp.rst => Documentation/howto/lisp.rst (100%)
rename README-native-tunneling.rst => Documentation/howto/native-tunneling.rst
(100%)
rename ovn/CONTAINERS.OpenStack.rst =>
Documentation/howto/openstack-containers.rst (95%)
rename INSTALL.SELinux.rst => Documentation/howto/selinux.rst (97%)
rename INSTALL.SSL.rst => Documentation/howto/ssl.rst (98%)
rename vtep/README.ovs-vtep.rst => Documentation/howto/vtep.rst (94%)
create mode 100644 Documentation/index.rst
create mode 100644 Documentation/internals/authors.rst
rename REPORTING-BUGS.rst => Documentation/internals/bugs.rst (97%)
rename Documentation/{ => internals}/committer-grant-revocation.rst (99%)
rename Documentation/{ => internals}/committer-responsibilities.rst (94%)
rename datapath-windows/CodingStyle.rst =>
Documentation/internals/contributing/coding-style-windows.rst (95%)
rename CodingStyle.rst =>
Documentation/internals/contributing/coding-style.rst (99%)
rename DocumentationStyle.rst =>
Documentation/internals/contributing/documentation-style.rst (97%)
create mode 100644 Documentation/internals/contributing/index.rst
create mode 100644 Documentation/internals/contributing/submitting-patches.rst
create mode 100644 Documentation/internals/index.rst
create mode 100644 Documentation/internals/mailing-lists.rst
create mode 100644 Documentation/internals/maintainers.rst
rename Documentation/{ => internals}/release-process.rst (100%)
rename SECURITY.rst => Documentation/internals/security.rst (90%)
create mode 100644 Documentation/intro/index.rst
rename utilities/ovs-command-bashcomp.INSTALL.rst =>
Documentation/intro/install/bash-completion.rst (100%)
rename INSTALL.Debian.rst => Documentation/intro/install/debian.rst (94%)
rename INSTALL.DPDK-ADVANCED.rst =>
Documentation/intro/install/dpdk-advanced.rst (98%)
rename INSTALL.DPDK.rst => Documentation/intro/install/dpdk.rst (92%)
rename INSTALL.Fedora.rst => Documentation/intro/install/fedora.rst (88%)
rename INSTALL.rst => Documentation/intro/install/general.rst (97%)
create mode 100644 Documentation/intro/install/index.rst
rename INSTALL.NetBSD.rst => Documentation/intro/install/netbsd.rst (89%)
rename INSTALL.RHEL.rst => Documentation/intro/install/rhel.rst (87%)
rename INSTALL.userspace.rst => Documentation/intro/install/userspace.rst (92%)
rename INSTALL.Windows.rst => Documentation/intro/install/windows.rst (99%)
rename INSTALL.XenServer.rst => Documentation/intro/install/xenserver.rst (96%)
rename WHY-OVS.rst => Documentation/intro/why-ovs.rst (97%)
create mode 100644 Documentation/ref/index.rst
rename vswitchd/INTERNALS.rst => Documentation/topics/bonding.rst (94%)
rename datapath/README.rst => Documentation/topics/datapath.rst (100%)
rename DESIGN.rst => Documentation/topics/design.rst (100%)
create mode 100644 Documentation/topics/dpdk.rst
rename ovn/OVN-GW-HA.rst => Documentation/topics/high-availability.rst (100%)
create mode 100644 Documentation/topics/index.rst
rename IntegrationGuide.rst => Documentation/topics/integration.rst (89%)
rename OPENFLOW.rst => Documentation/topics/openflow.rst (93%)
rename Documentation/{OVSDB-replication.rst => topics/ovsdb-replication.rst}
(100%)
rename PORTING.rst => Documentation/topics/porting.rst (99%)
rename datapath-windows/DESIGN.rst => Documentation/topics/windows.rst (100%)
create mode 100644 Documentation/tutorials/index.rst
rename tutorial/ovn-tutorial.rst => Documentation/tutorials/ovn-basics.rst
(99%)
rename tutorial/tutorial.rst => Documentation/tutorials/ovs-advanced.rst (99%)
delete mode 100644 FAQ.rst
--
2.7.4
_______________________________________________
dev mailing list
[email protected]
https://mail.openvswitch.org/mailman/listinfo/ovs-dev
