Prepare initial documentationn

* Adopt openstackdocstheme
* Document structure follows doc-migration spec
  https://review.openstack.org/#/c/472275/
* Release notes is generated as part of doc build to make
  doc publishing easy. neutron-vpnaas is not an official project
  and cannot publish it to docs.o.o.

Change-Id: I4fb1058fc078b32d549db3c66d91c85e0bdbe7a5

doc/source/conf.py

@@ -24,12 +24,13 @@
 
 from __future__ import print_function
 
-import django
 import os
-import subprocess
 import sys
-import warnings
 
+import django
+import openstackdocstheme
+
+PROJECT = 'neutron-vpnaas-dashboard'
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
 
@@ -62,7 +63,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
-    'oslosphinx',
+    'reno.sphinxext',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -133,8 +134,7 @@ nitpicky = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme_path = ['.']
-# html_theme = '_theme'
+html_theme = 'openstackdocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -144,7 +144,7 @@ html_theme_options = {
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -170,14 +170,18 @@ html_static_path = []
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'
-git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
-           "-n1"]
-try:
-    html_last_updated_fmt = subprocess.Popen(
-        git_cmd, stdout=subprocess.PIPE).communicate()[0]
-except Exception:
-    warnings.warn('Cannot get last updated time from git repository. '
-                  'Not setting "html_last_updated_fmt".')
+
+gitsha = os.popen("/usr/bin/git rev-parse HEAD").read()
+giturl = ('https://git.openstack.org/cgit/openstack/%s/tree/doc/source'
+          % PROJECT)
+html_context = {
+    'gitsha': gitsha,
+    'giturl': giturl,
+    'bug_project': PROJECT,
+    'bug_tag': 'doc',
+}
+html_last_updated_fmt = os.popen("git log --pretty=format:'%ad' "
+                                 "--date=format:'%Y-%m-%d %H:%M' -n1").read()
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

doc/source/configuration/index.rst

@@ -0,0 +1,28 @@
+..
+      Copyright 2017 OpenStack Foundation
+      All Rights Reserved.
+
+      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.
+
+=============
+Configuration
+=============
+
+Neutron VPNaaS dashboard has no configuration option.
+It checks if Neutron VPNaaS service is enabled in your neutron server
+and the VPNaaS panel is displayed if enabled.
+
+For more configurations, see
+`Deployment & Configuration
+<https://docs.openstack.org/developer/horizon/install/index.html>`__
+in the Horizon documentation.

doc/source/contributor/index.rst

@@ -0,0 +1,32 @@
+..
+      Copyright 2017 OpenStack Foundation
+      All Rights Reserved.
+
+      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.
+
+=================
+Contributor Guide
+=================
+
+There is no topic specific to neutron-vpnaas-dashboard now.
+
+See `Horizon Developer Documents
+<https://docs.openstack.org/developer/horizon/index.html#developer-docs>`__
+for general topic on developing a dashboard on horizon.
+
+----
+
+.. toctree::
+   :maxdepth: 1
+
+   DevStack plugin <devstack-plugin>

doc/source/index.rst

@@ -23,7 +23,11 @@ Neutron VPNaaS Dashboard is a horizon plugin for Neutron VPNaaS.
 User Documentation
 ------------------
 
-Under preparing.
+.. toctree::
+   :maxdepth: 1
+
+   install/index
+   configuration/index
 
 Contributor Guide
 -----------------
@@ -31,9 +35,12 @@ Contributor Guide
 .. toctree::
    :maxdepth: 1
 
-   contributor/devstack-plugin
+   contributor/index
 
 Release Notes
 -------------
 
-See http://docs.openstack.org/releasenotes/neutron-vpnaas-dashboard/.
+.. toctree::
+   :maxdepth: 1
+
+   Release Notes <releasenotes/index>

doc/source/install/index.rst

@@ -0,0 +1,81 @@
+..
+      Copyright 2017 OpenStack Foundation
+      All Rights Reserved.
+
+      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.
+
+============
+Installation
+============
+
+Manual Installation
+-------------------
+
+Before installing neutron-vpnaas-dashboard,
+you first need to install horizon in your environment.
+
+Fetch the source code from git and run pip install.
+Make sure to install neutron-vpnaas-dashboard into the same python environment
+where horizon is installed.
+
+.. code-block:: console
+
+   $ git clone https://git.openstack.org//openstack/neutron-vpnaas-dashboard
+   $ cd neutron-vpnaas-dashboard
+   $ sudo pip install .
+
+Enable the horizon plugin.
+
+.. code-block:: console
+
+   $ cp neutron_vpnaas_dashboard/enabled/_1470_project_vpn_panel.py \
+         /opt/stack/horizon/openstack_dashboard/local/enabled/_1470_project_vpn_panel.py
+
+.. note::
+
+   The directory ``local/enabled`` may be different depending on your
+   environment or distribution used. For example, for Ubuntu, this is
+   ``/usr/share/openstack-dashboard/openstack_dashboard/local/enabled``.
+
+.. note::
+
+   The number of the plugin enabled file determines the order of panels.
+   If you would like to configure the place of the Neutron VPNaaS dashboard,
+   change the number of the file.
+
+.. note::
+
+   For more detail of the horizon plugin settings,
+   see `Pluggable Settings
+   <https://docs.openstack.org/developer/horizon/install/settings.html#pluggable-settings>`__
+   in the horizon documentation.
+
+Compile the message catalogs of Neutron VPNaaS dashboard.
+
+.. code-block:: console
+
+   $ cd neutron-vpnaas-dashboard
+   $ ./manage.py compilemessages
+
+Run the Django update commands (if you use).
+
+.. code-block:: console
+
+   $ DJANGO_SETTINGS_MODULE=openstack_dashboard.settings python manage.py collectstatic --noinput
+   $ DJANGO_SETTINGS_MODULE=openstack_dashboard.settings python manage.py compress --force
+
+Restart Apache:
+
+.. code-block:: console
+
+   $ sudo service apache2 restart

doc/source/releasenotes

@@ -0,0 +1 @@
+../../releasenotes/source

releasenotes/source/conf.py

@@ -29,6 +29,12 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os
+
+import openstackdocstheme
+
+PROJECT = 'neutron-vpnaas-dashboard'
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -38,7 +44,6 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'oslosphinx',
     'reno.sphinxext',
 ]
 
@@ -56,7 +61,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Neutron VPNaaS Dashboard Release Notes'
-copyright = u'2016, OpenStack Foundation'
+copyright = u'2017, OpenStack Foundation'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -112,7 +117,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'openstackdocs'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -120,7 +125,7 @@ html_theme = 'default'
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -192,5 +197,17 @@ html_static_path = []
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'neutronvpnaasdashboardReleaseNotesdoc'
 
+gitsha = os.popen("/usr/bin/git rev-parse HEAD").read()
+giturl = ('https://git.openstack.org/cgit/openstack/%s/tree/doc/source'
+          % PROJECT)
+html_context = {
+    'gitsha': gitsha,
+    'giturl': giturl,
+    'bug_project': PROJECT,
+    'bug_tag': 'doc',
+}
+html_last_updated_fmt = os.popen("git log --pretty=format:'%ad' "
+                                 "--date=format:'%Y-%m-%d %H:%M' -n1").read()
+
 # -- Options for Internationalization output ------------------------------
 locale_dirs = ['locale/']

test-requirements.txt

@@ -11,7 +11,7 @@ mock>=2.0 # BSD
 mox3!=0.19.0,>=0.7.0 # Apache-2.0
 python-subunit>=0.0.18 # Apache-2.0/BSD
 sphinx!=1.6.1,>=1.5.1 # BSD
-oslosphinx>=4.7.0 # Apache-2.0
+openstackdocstheme>=1.5.0  # Apache-2.0
 testrepository>=0.0.18 # Apache-2.0/BSD
 testscenarios>=0.4 # Apache-2.0/BSD
 testtools>=1.4.0 # MIT