diff mbox

[ovs-dev,3/6] doc: Add info on building documentation

Message ID 20161217222342.21653-3-stephen@that.guru
State Accepted
Headers show

Commit Message

Stephen Finucane Dec. 17, 2016, 10:23 p.m. UTC 
I know how to do this, but does anyone else? Let's make it obvious and
ease the cognitive load on the great folks writing docs.

Links to the various packaging guides, previously missing, are included
on the main page.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 Documentation/automake.mk                     |  4 +-
 Documentation/index.rst                       |  7 ++-
 Documentation/intro/install/documentation.rst | 89 +++++++++++++++++++++++++++
 Documentation/intro/install/index.rst         | 10 ++-
 Documentation/requirements.txt                |  1 +
 5 files changed, 108 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/intro/install/documentation.rst
 create mode 100644 Documentation/requirements.txt

Comments

Ben Pfaff Dec. 21, 2016, 9:49 p.m. UTC | #1 
On Sat, Dec 17, 2016 at 10:23:39PM +0000, Stephen Finucane wrote:
> I know how to do this, but does anyone else? Let's make it obvious and
> ease the cognitive load on the great folks writing docs.
> 
> Links to the various packaging guides, previously missing, are included
> on the main page.
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>

I had to rewind the master branch to just before this patch, because it
adds a dependency on "requirements.txt" that isn't anywhere in the tree:

> @@ -68,7 +69,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 \
> +	requirements.txt

I'm happy to re-apply this patch and the rest of the series when that's
resolved.

Thanks,

Ben.
diff mbox

Patch

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index b02d63e..996bbf6 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-advanced.rst \
 	Documentation/intro/install/dpdk.rst \
 	Documentation/intro/install/fedora.rst \
@@ -68,7 +69,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 \
+	requirements.txt
 
 # You can set these variables from the command line.
 SPHINXOPTS =
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 8484dbd..fa9dca5 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -63,6 +63,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
 ------------------------
 
@@ -82,7 +86,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 0000000..1160e94
--- /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 2366388..d73e063 100644
--- a/Documentation/intro/install/index.rst
+++ b/Documentation/intro/install/index.rst
@@ -50,7 +50,6 @@  Installation from Source
    userspace
    dpdk
    dpdk-advanced
-   bash-completion
 
 Installation from Packages
 --------------------------
@@ -65,3 +64,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 0000000..354d3d0
--- /dev/null
+++ b/Documentation/requirements.txt
@@ -0,0 +1 @@ 
+sphinx>=1.3