[ovs-dev] [PATCH v2 00/11] Sphinx-ification of documentation
Stephen Finucane
stephen at that.guru
Thu Dec 8 12:55:19 UTC 2016
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
All other comments from the original series cover letter still apply.
https://mail.openvswitch.org/pipermail/ovs-dev/2016-November/325292.html
Changes since v1:
- Rebase onto master
Stephen Finucane (11):
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 +
CONTRIBUTING.rst | 430 +---
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 | 2 +-
.../{ => 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 | 452 +++++
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/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 | 4 +-
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 +-
113 files changed, 4365 insertions(+), 2963 deletions(-)
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.9.3
More information about the dev
mailing list