diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/automake.mk | 4 | ||||
| -rw-r--r-- | Documentation/index.rst | 7 | ||||
| -rw-r--r-- | Documentation/intro/install/documentation.rst | 89 | ||||
| -rw-r--r-- | Documentation/intro/install/index.rst | 10 | ||||
| -rw-r--r-- | Documentation/requirements.txt | 1 |
5 files changed, 108 insertions, 3 deletions
diff --git a/Documentation/automake.mk b/Documentation/automake.mk index bc8bef3bd..b488807ef 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -9,6 +9,7 @@ EXTRA_DIST += \ Documentation/intro/install/index.rst \ Documentation/intro/install/bash-completion.rst \ Documentation/intro/install/debian.rst \ + Documentation/intro/install/documentation.rst \ Documentation/intro/install/dpdk.rst \ Documentation/intro/install/fedora.rst \ Documentation/intro/install/general.rst \ @@ -80,7 +81,8 @@ EXTRA_DIST += \ Documentation/internals/contributing/coding-style.rst \ Documentation/internals/contributing/coding-style-windows.rst \ Documentation/internals/contributing/documentation-style.rst \ - Documentation/internals/contributing/submitting-patches.rst + Documentation/internals/contributing/submitting-patches.rst \ + Documentation/requirements.txt # You can set these variables from the command line. SPHINXOPTS = diff --git a/Documentation/index.rst b/Documentation/index.rst index f4104872f..32b41e17e 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -76,6 +76,10 @@ Deeper Dive - **Reference Guides:** :doc:`ref/index` +- **Packaging:** :doc:`intro/install/debian` | + :doc:`intro/install/rhel` | + :doc:`intro/install/fedora` + The Open vSwitch Project ------------------------ @@ -96,7 +100,8 @@ Learn more about the Open vSwitch project and about how you can contribute: :doc:`internals/committer-responsibilities` | :doc:`internals/committer-grant-revocation` -- **Documentation:** :doc:`internals/contributing/documentation-style` +- **Documentation:** :doc:`internals/contributing/documentation-style` | + :doc:`Building Open vSwitch Documentation <intro/install/documentation>` Getting Help ------------- diff --git a/Documentation/intro/install/documentation.rst b/Documentation/intro/install/documentation.rst new file mode 100644 index 000000000..1160e9423 --- /dev/null +++ b/Documentation/intro/install/documentation.rst @@ -0,0 +1,89 @@ +.. + Copyright (c) 2016 Stephen Finucane <stephen@that.guru> + + 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 + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +========================== +Open vSwitch Documentation +========================== + +This document describes how to build the OVS documentation for use offline. A +continuously updated, online version can be found at `docs.openvswitch.org +<http://docs.openvswitch.org>`__. + +.. note:: + These instructions provide information on building the documentation locally. + For information on writing documentation, refer to + :doc:`/internals/contributing/documentation-style` + +Build Requirements +------------------ + +As described in the :doc:`/internals/contributing/documentation-style`, the +Open vSwitch documentation is written in reStructuredText and built with +Sphinx. A detailed guide on installing Sphinx in many environments is available +on the `Sphinx website`__ but, for most Linux distributions, you can install +with your package manager. For example, on Debian/Ubuntu run:: + + $ sudo apt-get install python-sphinx + +Similarly, on RHEL/Fedora run:: + + $ sudo dnf install python-sphinx + +A ``requirements.txt`` is also provided in the ``/Documentation``, should you +wish to install using ``pip``:: + + $ virtualenv .venv + $ source .venv/bin/activate + $ pip install -r Documentation/requirements.txt + +__ http://www.sphinx-doc.org/install.html + +Configuring +----------- + +It's unlikely that you'll need to customize any aspect of the configuration. +However, the ``Documentation/conf.py`` is the go-to place for all +configuration. This file is well documented and further information is +available on the `Sphinx website`__. + +Building +-------- + +Once Sphinx installed, the documentation can be built using the provided +Makefile targets:: + + $ make htmldocs + +.. important:: + + The ``htmldocs`` target will fail if there are any syntax errors. However, + it won't catch more succint issues such as style or grammar issues. As a + result, you should always inspect changes visually to ensure the result is + as intended. + +Once built, documentation is available in the ``/Documentation/_build`` folder. +Open the root ``index.html`` to browse the documentation. + +__ http://www.sphinx-doc.org/config.html diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst index 0d3ea0604..34b014aa6 100644 --- a/Documentation/intro/install/index.rst +++ b/Documentation/intro/install/index.rst @@ -45,7 +45,6 @@ Installation from Source xenserver userspace dpdk - bash-completion Installation from Packages -------------------------- @@ -60,3 +59,12 @@ provided below. debian fedora rhel + +Others +------ + +.. toctree:: + :maxdepth: 2 + + bash-completion + documentation diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt new file mode 100644 index 000000000..354d3d0d8 --- /dev/null +++ b/Documentation/requirements.txt @@ -0,0 +1 @@ +sphinx>=1.3 |