This way it's easier to show it on a website as it will be updated
automatically along with the rest of the documentation.
Sphinx doesn't render everything perfectly, but it looks good enough
in both man and html versions. rST is a bit easier to read and it
takes less space.
Conversion performed manually since I didn't found any good tool
that can actually make the process any faster.
Along the way I replaced versions like x.y.90 with x.y+1, because
it doesn't seem correct to me to refer non-released versions of OVS
in the docs. Fixed a couple of small mistakes like duplicated
paragraph and reference to a different section by incorrect name.
Also removed bits of xml->nroff conversion code that is not needed
anymore.
Signed-off-by: Ilya Maximets <i.maximets@ovn.org>
Acked-by: Roi Dayan <roid@nvidia.com>
open(), io.open(), codecs.open() and fileinput.FileInput no longer accept 'U'
("universal newline") in the file mode.
This flag was deprecated since Python 3.3.
In Python 3, the "universal newline" is used by default when a file is open
in text mode.
Acked-by: Flavio Leitner <fbl@sysclose.org>
Reported-at: https://bugzilla.redhat.com/1791681
Reported-by: Miro Hrončok <mhroncok@redhat.com>
Signed-off-by: Timothy Redaelli <tredaelli@redhat.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
These ports are used to allow ingress/egress from the host and are
therefore _reasonably_ important. However, there is no clear overview of
what these ports actually are or why things are done the way they are.
Start closing this gap by providing a standalone example of using these
ports along with a little more detailed overview of the binding process.
There is additional cleanup to be done for the DPDK howto, but that will
be done separately.
We enable the TODO directive so we can actually start calling out some
TODOs.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ian Stokes <ian.stokes@intel.com>
A previous commit introduced a line that was greater than 79
characters long, causing a flake8 warning to be emitted.
Reported-by: Joe Stringer <joe@ovn.org>
Fixes: 5ca89127382d ("docs: Refer to correct package name for sphinx theme.")
Signed-off-by: Russell Bryant <russell@ovn.org>
Update the log message emitted when the OVS sphinx theme is not found
to reference the name of the package to be installed via pip:
ovs-sphinx-theme.
Signed-off-by: Russell Bryant <russell@ovn.org>
Acked-by: Lance Richardson <lrichard@redhat.com>
All these entries are going to be roughly the same, with only two key
differences. Clarify things by focusing on those differences.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Sphinx 1.3 renamed the 'default' theme to 'classic' and configured the
'alabaster' theme as the new default. To prevent breaking existing
builds, the 'default' name was reserved as an alias for 'classic' [1].
However, initially this raised a warning [1] with a message to use
'classic' instead. This warning was removed in 1.3.2 [2], but it will
result in errors (due to the use of the '-W' flag) for Sphinx 1.3.0 and
1.3.1 users.
Mitigate the issue by not setting a theme if the 'ovs_sphinx_theme'
package is absent. This will result in Sphinx using its default theme,
be that 'classic' (Sphinx < 1.3) or 'alabaster'.
[1] https://github.com/sphinx-doc/sphinx/commit/68021b0bd
[2] https://github.com/sphinx-doc/sphinx/commit/034c4e942
Signed-off-by: Stephen Finucane <stephen@that.guru>
Cc: Matthew Thode <mthode@mthode.org>
Signed-off-by: Ben Pfaff <blp@ovn.org>
This file has enough going on as-is without keeping all this commented
out noise around.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Let's start with a simple one that lets us focus on setting up most of
the required "infrastructure" for building man pages using Sphinx.
This changes the 'check-htmldocs' target to 'check-docs' as its now
responsible for building man page docs too.
Other than that, hurrah for (mostly) legible syntaxes.
[1] http://www.tldp.org/HOWTO/Man-Page/q2.html
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
It's awkward to have to at the same time generate conf.py from conf.py.in
and to keep both versions in the repository. This avoids the issue.
Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Stephen Finucane <stephen@that.guru>
Update the version numbers in the documentation config to reflect 2.7.90
instead of 2.6.0.
This patch also updates the build system to automatically update this file.
conf.py is now a generated file from conf.py.in. We still include conf.py
in the tree because it's needed for the docs to be automatically generated
for docs.openvswitch.org.
Signed-off-by: Russell Bryant <russell@ovn.org>
Acked-by: Stephen Finucane <stephen@that.guru>
Sphinx 1.1.3 on RHEL7 is able to properly build the documentation.
Discovering fixed because 'sphinx-build v1.1.3' doesn't support
'--version' option.
Acked-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ilya Maximets <i.maximets@samsung.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Current documentation uses syntax highlighting in 'sphinx'
via 'pygments' library. This leads to build failures on the
systems with old version of this library.
In fact that only 'windows.rst' uses highlighting it's a
very simple change. This helps us to avoid build issues
on different systems and allows to remove painful external
dependency.
Signed-off-by: Ilya Maximets <i.maximets@samsung.com>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Build documentation as part of every build. This ensures any syntax
errors are caught early.
In addition, a 'check-docs' target is added to validates all external
links.
The nitpick ('-n') flag is added to ensure all possible warnings are
raised.
Signed-off-by: Stephen Finucane <stephen@that.guru>
[blp@ovn.org folded in changes for --enable-silent-rules]
Signed-off-by: Ben Pfaff <blp@ovn.org>
The recently published 'ovs' theme [1] copies the styling of the Open
vSwitch website. Start using this, with fallbacks for users who do not
have the package installed.
This extends support for building docs to users of Sphinx 1.2 as the
previous theme - bizstyle - was only available in 1.3+.
[1] https://pypi.python.org/pypi/ovs-sphinx-theme
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
This is essentially the output of 'sphinx-quickstart' but with the
following changes:
- Parts of the generated Makefile are merged into the existing
Documentation/automake.mk Makefile
- A license is added to the index.rst file
- The OVS logo is added
- A 'contents' page is added, so we don't need to include a TOC on the
home page
- The theme is switched to 'bizstyle', which makes better use of
horizontal real estate than the default 'alabaster' theme
Copyright is assigned to "The Open vSwitch Development Community".
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
