diff --git a/README.rst b/README.rst index 00915c1..efe5c2f 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/configure_access_and_security_for_instances.rst b/doc/source/demo/configure_access_and_security_for_instances.rst similarity index 100% rename from doc/source/configure_access_and_security_for_instances.rst rename to doc/source/demo/configure_access_and_security_for_instances.rst diff --git a/doc/source/create_and_manage_databases.rst b/doc/source/demo/create_and_manage_databases.rst similarity index 100% rename from doc/source/create_and_manage_databases.rst rename to doc/source/demo/create_and_manage_databases.rst diff --git a/doc/source/create_and_manage_networks.rst b/doc/source/demo/create_and_manage_networks.rst similarity index 100% rename from doc/source/create_and_manage_networks.rst rename to doc/source/demo/create_and_manage_networks.rst diff --git a/doc/source/dashboard_demo.rst b/doc/source/demo/dashboard_demo.rst similarity index 100% rename from doc/source/dashboard_demo.rst rename to doc/source/demo/dashboard_demo.rst diff --git a/doc/source/figures/dashboard-project-tab.png b/doc/source/demo/figures/dashboard-project-tab.png similarity index 100% rename from doc/source/figures/dashboard-project-tab.png rename to doc/source/demo/figures/dashboard-project-tab.png diff --git a/doc/source/figures/dashboard_admin_project_tab.png b/doc/source/demo/figures/dashboard_admin_project_tab.png similarity index 100% rename from doc/source/figures/dashboard_admin_project_tab.png rename to doc/source/demo/figures/dashboard_admin_project_tab.png diff --git a/doc/source/figures/doc-logo-fox.jpg b/doc/source/demo/figures/doc-logo-fox.jpg similarity index 100% rename from doc/source/figures/doc-logo-fox.jpg rename to doc/source/demo/figures/doc-logo-fox.jpg diff --git a/doc/source/demo/index.rst b/doc/source/demo/index.rst new file mode 100644 index 0000000..2dd5ee7 --- /dev/null +++ b/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` diff --git a/doc/source/launch-instance.rst b/doc/source/demo/launch-instance.rst similarity index 100% rename from doc/source/launch-instance.rst rename to doc/source/demo/launch-instance.rst diff --git a/doc/source/section_dashboard_access_and_security.rst b/doc/source/demo/section_dashboard_access_and_security.rst similarity index 100% rename from doc/source/section_dashboard_access_and_security.rst rename to doc/source/demo/section_dashboard_access_and_security.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 2dd5ee7..97f9b4b 100644 --- a/doc/source/index.rst +++ b/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`