move documentation from readme to sphinx tree

Move the existing test docs into a subdirectory and move the setup
details from the README to docs/source/index.rst.

Change-Id: Ic66247a1d5527cf1ba34f3b1561de6a027e12050
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

README.rst

@@ -15,68 +15,10 @@ docs.openstack.org and developer.openstack.org.
 
 Intended for use by OpenStack `projects governed by the Technical Committee`_.
 
-.. _`projects governed by the Technical Committee`:
-https://governance.openstack.org/reference/projects/index.html
-
-Using the Theme
-===============
-
-Prior to using this theme, ensure your project can use the OpenStack
-brand by referring to the brand guidelines at
-https://www.openstack.org/brand.
-
-Update the requirements list for your project to
-include ``openstackdocstheme`` (usually in test-requirements.txt).
-
-If your project previously used the oslosphinx theme (without modifying
-the header navigation), remove oslosphinx from your requirements list,
-and then in your ``conf.py`` you can remove the import statement and
-extension listing for oslosphinx.
-
-Some of the settings below are included in the file generated by Sphinx when
-you initialize a project, so they may already have values that need to be
-changed.
-
-Then modify your Sphinx settings in ``conf.py`` to include::
-
-   html_theme = 'openstackdocs'
-
-and to add ``'openstackdocstheme'`` to the list of extensions Sphinx
-needs to initialize::
-
-   extensions = [
-       # ...
-       'openstackdocstheme',
-       # ...
-   ]
-
-Set the options to link to the git repository and bug tracker.
-
-``repository_name``
-    The prefix and repo name. For example,
-    ``'openstack/python-glanceclient'``.
-
-``bug_project``
-    The launchpad project name. For example, ``python-glanceclient``.
-
-``bug_tag``
-   Launchpad bug tag. If unspecified, no tag is set.  The default is
-   empty.
-
-For example::
-
-    # openstackdocstheme options
-    repository_name = 'openstack/python-glanceclient'
-    bug_project = 'python-glanceclient'
-    bug_tag = ''
-
-Enable the "last-updated" information by setting the format for the
-timestamp::
-
-   # Must set this variable to include year, month, day, hours, and minutes.
-   html_last_updated_fmt = '%Y-%m-%d %H:%M'
+.. _`projects governed by the Technical Committee`: https://governance.openstack.org/reference/projects/index.html
 
 * Free software: Apache License, Version 2.0
+* Documentation: https://docs.openstack.org/openstackdocstheme/latest/
 * Release notes: https://docs.openstack.org/releasenotes/openstackdocstheme/
 * Source: https://git.openstack.org/cgit/openstack/openstackdocstheme
 * Bugs: https://launchpad.net/openstack-doc-tools

doc/source/demo/index.rst

@@ -0,0 +1,100 @@
+.. os-doc-demo documentation master file, created by
+   sphinx-quickstart on Tue Jan 20 08:22:27 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. highlight: python
+   :linenothreshold: 5
+
+.. figure:: figures/doc-logo-fox.jpg
+   :alt: Documentation Logo
+   :scale: 30%
+   :align: center
+
+Demo documentation
+==================
+
+The demo documentation provides example markup for looking at the expected output.
+
+The project aims for simple implementation, massive scalability, and a rich set
+of features. Cloud computing experts from around the world contribute to the project.
+
+Here's an example glossary:
+
+Cactus
+   An OpenStack grouped release of projects that came out in the spring of
+   2011. It included Compute (nova), Object Storage (swift), and the Image
+   service (glance). Cactus is a city in Texas, US and is the code name for
+   the third release of OpenStack. When OpenStack releases went from three to
+   six months long, the code name of the release changed to match a geography
+   nearest the previous summit.
+
+CADF
+    Cloud Auditing Data Federation (CADF) is a specification for audit event
+    data. CADF is supported by OpenStack Identity.
+
+CALL
+    One of the RPC primitives used by the OpenStack message queue software.
+    Sends a message and waits for a response.
+
+Here's an example configuration::
+
+   [DEFAULT]
+   ...
+   my_ip = 10.0.0.31
+   vnc_enabled = True
+   vncserver_listen = 0.0.0.0
+   vncserver_proxyclient_address = 10.0.0.31
+   novncproxy_base_url = http://controller:6080/vnc_auto.html
+
+
+Here's another example that's python code:
+
+.. code-block:: python
+    :linenos:
+
+    def builder_inited(app):
+        theme_dir = os.path.join(os.path.dirname(__file__), 'theme')
+        app.info('Using openstack theme from %s' % theme_dir)
+        # Insert our theme directory at the front of the search path and
+        # force the theme setting to use the one in the package. This is
+        # done here, instead of in setup(), because conf.py is read after
+        # setup() runs, so if the conf contains these values the user
+        # values overwrite these. That's not bad for the theme, but it
+        # breaks the search path.
+        app.config.html_theme_path.insert(0, theme_dir)
+        # Set the theme name
+        app.config.html_theme = 'openstack'
+        # Re-initialize the builder, if it has the method for setting up
+        # the templates and theme.
+        if hasattr(app.builder, 'init_templates'):
+            app.builder.init_templates()
+
+Here's the same example but with ..code-block: ini to test the pygments lexer:
+
+.. code-block:: ini
+
+  [DEFAULT]
+  ...
+  my_ip = 10.0.0.31
+  vnc_enabled = True
+  vncserver_listen = 0.0.0.0
+  vncserver_proxyclient_address = 10.0.0.31
+  novncproxy_base_url = http://controller:6080/vnc_auto.html
+
+.. note:: Here's an example note.
+
+.. toctree::
+    :maxdepth: 1
+
+    section_dashboard_access_and_security
+    dashboard_demo
+    configure_access_and_security_for_instances
+    create_and_manage_databases
+    create_and_manage_networks
+    launch-instance
+
+Search
+~~~~~~
+
+* :ref:`search`

doc/source/index.rst

@@ -1,100 +1,99 @@
-.. os-doc-demo documentation master file, created by
-   sphinx-quickstart on Tue Jan 20 08:22:27 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+===========================================
+ OpenStack docs.openstack.org Sphinx Theme
+===========================================
 
-.. highlight: python
-   :linenothreshold: 5
+``openstackdocstheme`` is a theme and extension support for Sphinx
+documentation that is published to docs.openstack.org and
+developer.openstack.org.
 
-.. figure:: figures/doc-logo-fox.jpg
-   :alt: Documentation Logo
-   :scale: 30%
-   :align: center
+It is intended for use by OpenStack `projects governed by the
+Technical Committee`_.
 
-Demo documentation
-==================
+.. _`projects governed by the Technical Committee`: https://governance.openstack.org/reference/projects/index.html
 
-The demo documentation provides example markup for looking at the expected output.
+Using the Theme
+===============
 
-The project aims for simple implementation, massive scalability, and a rich set
-of features. Cloud computing experts from around the world contribute to the project.
+.. note::
 
-Here's an example glossary:
+   Prior to using this theme, ensure your project can use the
+   OpenStack brand by referring to the brand guidelines at
+   https://www.openstack.org/brand.
 
-Cactus
-   An OpenStack grouped release of projects that came out in the spring of
-   2011. It included Compute (nova), Object Storage (swift), and the Image
-   service (glance). Cactus is a city in Texas, US and is the code name for
-   the third release of OpenStack. When OpenStack releases went from three to
-   six months long, the code name of the release changed to match a geography
-   nearest the previous summit.
+.. note::
 
-CADF
-    Cloud Auditing Data Federation (CADF) is a specification for audit event
-    data. CADF is supported by OpenStack Identity.
+   Some of the settings below are included in the file generated by
+   Sphinx when you initialize a project, so they may already have
+   values that need to be changed.
 
-CALL
-    One of the RPC primitives used by the OpenStack message queue software.
-    Sends a message and waits for a response.
+#. Update the requirements list for your project to include
+   ``openstackdocstheme`` (usually in test-requirements.txt).
 
-Here's an example configuration::
+#. If your project previously used the oslosphinx theme (without
+   modifying the header navigation), remove ``oslosphinx`` from your
+   requirements list, and then in your ``conf.py`` you can remove the
+   import statement and extension listing for oslosphinx.
 
-   [DEFAULT]
-   ...
-   my_ip = 10.0.0.31
-   vnc_enabled = True
-   vncserver_listen = 0.0.0.0
-   vncserver_proxyclient_address = 10.0.0.31
-   novncproxy_base_url = http://controller:6080/vnc_auto.html
+#. Then modify your Sphinx settings in ``conf.py`` to include::
+
+     html_theme = 'openstackdocs'
+
+#. and to add ``'openstackdocstheme'`` to the list of extensions
+   Sphinx needs to initialize::
+
+     extensions = [
+         # ...
+         'openstackdocstheme',
+         # ...
+     ]
+
+#. Set the options to link to the git repository and bug tracker.
+
+   ``repository_name``
+       The prefix and repo name. For example,
+       ``'openstack/python-glanceclient'``.
+
+   ``bug_project``
+       The launchpad project name. For example, ``python-glanceclient``.
+
+   ``bug_tag``
+      Launchpad bug tag. If unspecified, no tag is set.  The default is
+      empty.
+
+   For example::
+
+      # openstackdocstheme options
+      repository_name = 'openstack/python-glanceclient'
+      bug_project = 'python-glanceclient'
+      bug_tag = ''
+
+#. Enable the "last-updated" information by setting the format for the
+   timestamp::
+
+     # Must set this variable to include year, month, day, hours, and minutes.
+     html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+#. If you are using this theme for API reference documentation, set the sidebar
+   navigation in the `html_theme_options` in the `conf.py` file::
+
+     # To use the API Reference sidebar dropdown menu,
+     # uncomment the html_theme_options parameter.  The theme
+     # variable, sidebar_dropdown, should be set to `api_ref`.
+     # Otherwise, the list of links for the User and Ops docs
+     # appear in the sidebar dropdown menu.
+     html_theme_options = {"sidebar_dropdown": "api_ref",
+                           "sidebar_mode": "toc"}
 
 
-Here's another example that's python code:
+Demonstration example
+=====================
 
-.. code-block:: python
-    :linenos:
-
-    def builder_inited(app):
-        theme_dir = os.path.join(os.path.dirname(__file__), 'theme')
-        app.info('Using openstack theme from %s' % theme_dir)
-        # Insert our theme directory at the front of the search path and
-        # force the theme setting to use the one in the package. This is
-        # done here, instead of in setup(), because conf.py is read after
-        # setup() runs, so if the conf contains these values the user
-        # values overwrite these. That's not bad for the theme, but it
-        # breaks the search path.
-        app.config.html_theme_path.insert(0, theme_dir)
-        # Set the theme name
-        app.config.html_theme = 'openstack'
-        # Re-initialize the builder, if it has the method for setting up
-        # the templates and theme.
-        if hasattr(app.builder, 'init_templates'):
-            app.builder.init_templates()
-
-Here's the same example but with ..code-block: ini to test the pygments lexer:
-
-.. code-block:: ini
-
-  [DEFAULT]
-  ...
-  my_ip = 10.0.0.31
-  vnc_enabled = True
-  vncserver_listen = 0.0.0.0
-  vncserver_proxyclient_address = 10.0.0.31
-  novncproxy_base_url = http://controller:6080/vnc_auto.html
-
-.. note:: Here's an example note.
+The demo documentation provides example output to ensure it matches what's
+expected. The link below points to the example output when using the theme
+for all documentation that is not API reference.
 
 .. toctree::
-    :maxdepth: 1
+   :maxdepth: 1
 
-    section_dashboard_access_and_security
-    dashboard_demo
-    configure_access_and_security_for_instances
-    create_and_manage_databases
-    create_and_manage_networks
-    launch-instance
+   demo/index
 
-Search
-~~~~~~
-
-* :ref:`search`