Merge "move documentation from readme to sphinx tree"
This commit is contained in:
commit
36cc0ab48b
62
README.rst
62
README.rst
|
@ -15,68 +15,10 @@ docs.openstack.org and developer.openstack.org.
|
||||||
|
|
||||||
Intended for use by OpenStack `projects governed by the Technical Committee`_.
|
Intended for use by OpenStack `projects governed by the Technical Committee`_.
|
||||||
|
|
||||||
.. _`projects governed by the Technical Committee`:
|
.. _`projects governed by the Technical Committee`: https://governance.openstack.org/reference/projects/index.html
|
||||||
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'
|
|
||||||
|
|
||||||
* Free software: Apache License, Version 2.0
|
* Free software: Apache License, Version 2.0
|
||||||
|
* Documentation: https://docs.openstack.org/openstackdocstheme/latest/
|
||||||
* Release notes: https://docs.openstack.org/releasenotes/openstackdocstheme/
|
* Release notes: https://docs.openstack.org/releasenotes/openstackdocstheme/
|
||||||
* Source: https://git.openstack.org/cgit/openstack/openstackdocstheme
|
* Source: https://git.openstack.org/cgit/openstack/openstackdocstheme
|
||||||
* Bugs: https://launchpad.net/openstack-doc-tools
|
* Bugs: https://launchpad.net/openstack-doc-tools
|
||||||
|
|
Before Width: | Height: | Size: 73 KiB After Width: | Height: | Size: 73 KiB |
Before Width: | Height: | Size: 71 KiB After Width: | Height: | Size: 71 KiB |
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 42 KiB |
|
@ -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`
|
|
@ -1,100 +1,99 @@
|
||||||
.. os-doc-demo documentation master file, created by
|
===========================================
|
||||||
sphinx-quickstart on Tue Jan 20 08:22:27 2015.
|
OpenStack docs.openstack.org Sphinx Theme
|
||||||
You can adapt this file completely to your liking, but it should at least
|
===========================================
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
|
||||||
.. highlight: python
|
``openstackdocstheme`` is a theme and extension support for Sphinx
|
||||||
:linenothreshold: 5
|
documentation that is published to docs.openstack.org and
|
||||||
|
developer.openstack.org.
|
||||||
|
|
||||||
.. figure:: figures/doc-logo-fox.jpg
|
It is intended for use by OpenStack `projects governed by the
|
||||||
:alt: Documentation Logo
|
Technical Committee`_.
|
||||||
:scale: 30%
|
|
||||||
:align: center
|
|
||||||
|
|
||||||
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
|
.. note::
|
||||||
of features. Cloud computing experts from around the world contribute to the project.
|
|
||||||
|
|
||||||
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
|
.. note::
|
||||||
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
|
Some of the settings below are included in the file generated by
|
||||||
Cloud Auditing Data Federation (CADF) is a specification for audit event
|
Sphinx when you initialize a project, so they may already have
|
||||||
data. CADF is supported by OpenStack Identity.
|
values that need to be changed.
|
||||||
|
|
||||||
CALL
|
#. Update the requirements list for your project to include
|
||||||
One of the RPC primitives used by the OpenStack message queue software.
|
``openstackdocstheme`` (usually in test-requirements.txt).
|
||||||
Sends a message and waits for a response.
|
|
||||||
|
|
||||||
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]
|
#. Then modify your Sphinx settings in ``conf.py`` to include::
|
||||||
...
|
|
||||||
my_ip = 10.0.0.31
|
html_theme = 'openstackdocs'
|
||||||
vnc_enabled = True
|
|
||||||
vncserver_listen = 0.0.0.0
|
#. and to add ``'openstackdocstheme'`` to the list of extensions
|
||||||
vncserver_proxyclient_address = 10.0.0.31
|
Sphinx needs to initialize::
|
||||||
novncproxy_base_url = http://controller:6080/vnc_auto.html
|
|
||||||
|
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
|
The demo documentation provides example output to ensure it matches what's
|
||||||
:linenos:
|
expected. The link below points to the example output when using the theme
|
||||||
|
for all documentation that is not API reference.
|
||||||
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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
section_dashboard_access_and_security
|
demo/index
|
||||||
dashboard_demo
|
|
||||||
configure_access_and_security_for_instances
|
|
||||||
create_and_manage_databases
|
|
||||||
create_and_manage_networks
|
|
||||||
launch-instance
|
|
||||||
|
|
||||||
Search
|
|
||||||
~~~~~~
|
|
||||||
|
|
||||||
* :ref:`search`
|
|
||||||
|
|
Loading…
Reference in New Issue