Doc cleanup, use openstackdocstheme
Switch to "modern" way of docs building in OpenStack:
* Use sphinx-build
* Use openstackdocstheme instead of old oslosphinx
* Adjust settings for openstackdocstheme
* Fix build errors:
- There's no priorities folder in this repo,
so remove non-existing links.
- There's no backlog file, remove link.
- remove links in specs that don't exist
- fix RST link formatting
- Fix RST errors
Change-Id: I0d1d1c866957e7dbd5d4e394b0368a0a5250b00b
This commit is contained in:
Andreas Jaeger
parent
958a432bca
commit
77dfcdd291
@ -12,8 +12,8 @@
|
||||
# serve to show the default.
|
||||
|
||||
import datetime
|
||||
import sys
|
||||
import os
|
||||
import sys
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
@ -28,13 +28,17 @@ sys.path.insert(0, os.path.abspath('.'))
|
||||
# Add any Sphinx extension module names here, as strings. They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ['redirect',
|
||||
'sphinx.ext.autodoc',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx.ext.viewcode',
|
||||
'oslosphinx',
|
||||
'openstackdocstheme',
|
||||
'yasfb',
|
||||
]
|
||||
|
||||
# Settings for openstackdocstheme
|
||||
repository_name = 'openstack/charm-specs'
|
||||
bug_project = 'charm-specs'
|
||||
bug_tag = u''
|
||||
|
||||
# Feed configuration for yasfb
|
||||
feed_base_url = 'http://specs.openstack.org/openstack/charm-specs'
|
||||
feed_author = 'OpenStack Charm Team'
|
||||
@ -100,11 +104,7 @@ man_pages = []
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
on_rtd = os.environ.get('READTHEDOCS') == 'True'
|
||||
if on_rtd:
|
||||
html_theme = 'default'
|
||||
else:
|
||||
html_theme = 'nature'
|
||||
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
|
||||
@ -130,11 +130,6 @@ else:
|
||||
# pixels large.
|
||||
#html_favicon = None
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
|
||||
html_last_updated_fmt = os.popen(git_cmd).read()
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
#html_use_smartypants = True
|
||||
@ -178,17 +173,6 @@ htmlhelp_basename = 'Charm-Specsdoc'
|
||||
|
||||
# -- Options for LaTeX output --------------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#'preamble': '',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass [howto/manual]).
|
||||
latex_documents = [
|
||||
|
||||
@ -1,28 +1,7 @@
|
||||
.. charm-specs documentation master file
|
||||
|
||||
=============================
|
||||
OpenStack Charm Project Plans
|
||||
=============================
|
||||
|
||||
Priorities
|
||||
==========
|
||||
|
||||
During each design summit, we agree what the whole community wants to focus
|
||||
on for the upcoming release. This is the output of those discussions:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
priorities/ussuri-priorities
|
||||
priorities/train-priorities
|
||||
priorities/stein-priorities
|
||||
priorities/rocky-priorities
|
||||
priorities/queens-priorities
|
||||
priorities/pike-priorities
|
||||
priorities/ocata-priorities
|
||||
priorities/newton-priorities
|
||||
|
||||
Specifications
|
||||
==============
|
||||
|
||||
@ -41,14 +20,6 @@ Here you can find the specs, and spec template, for each release:
|
||||
specs/ocata/index
|
||||
specs/newton/index
|
||||
|
||||
There are also some approved backlog specifications that are looking for owners:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
specs/backlog/index
|
||||
|
||||
Process
|
||||
=======
|
||||
|
||||
|
||||
@ -6,8 +6,12 @@
|
||||
import os.path
|
||||
|
||||
from sphinx.application import ENV_PICKLE_FILENAME
|
||||
from sphinx.util import logging
|
||||
from sphinx.util.console import bold
|
||||
|
||||
LOG = logging.getLogger(__name__)
|
||||
|
||||
|
||||
|
||||
def setup(app):
|
||||
from sphinx.application import Sphinx
|
||||
@ -35,7 +39,7 @@ def process_redirect_file(app, path, ent):
|
||||
|
||||
|
||||
def emit_redirects(app, exc):
|
||||
app.builder.info(bold('scanning %s for redirects...') % app.builder.srcdir)
|
||||
LOG.info(bold('scanning %s for redirects...') % app.builder.srcdir)
|
||||
|
||||
def process_directory(path):
|
||||
for ent in os.listdir(path):
|
||||
@ -43,8 +47,8 @@ def emit_redirects(app, exc):
|
||||
if os.path.isdir(p):
|
||||
process_directory(p)
|
||||
elif ent == 'redirects':
|
||||
app.builder.info(' found redirects at %s' % p)
|
||||
LOG.info(' found redirects at %s' % p)
|
||||
process_redirect_file(app, path, ent)
|
||||
|
||||
process_directory(app.builder.srcdir)
|
||||
app.builder.info('...done')
|
||||
LOG.info('...done')
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/newton/approved/
|
||||
@ -16,11 +16,3 @@ Newton implemented specs:
|
||||
:maxdepth: 1
|
||||
|
||||
implemented/*
|
||||
|
||||
Newton approved (but not implemented) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
approved/*
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/ocata/approved
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/ocata/backlog
|
||||
@ -16,19 +16,3 @@ Ocata implemented specs:
|
||||
:maxdepth: 1
|
||||
|
||||
implemented/*
|
||||
|
||||
Ocata approved (but not implemented) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
approved/*
|
||||
|
||||
Ocata backlog (carried over from previous cycle) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
backlog/*
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/pike/approved
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/pike/backlog
|
||||
@ -16,19 +16,3 @@ Pike implemented specs:
|
||||
:maxdepth: 1
|
||||
|
||||
implemented/*
|
||||
|
||||
Pike approved (but not implemented) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
approved/*
|
||||
|
||||
Pike backlog (carried over from previous cycle) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
backlog/*
|
||||
|
||||
@ -16,19 +16,3 @@ Queens implemented specs:
|
||||
:maxdepth: 1
|
||||
|
||||
implemented/*
|
||||
|
||||
Queens approved (but not implemented) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
approved/*
|
||||
|
||||
Queens backlog (carried over from previous cycle) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
backlog/*
|
||||
|
||||
@ -2,13 +2,6 @@
|
||||
Charm Rocky Specifications
|
||||
===========================
|
||||
|
||||
Template:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Specification Template (Rocky release) <template>
|
||||
|
||||
Rocky implemented specs:
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/stein/backlog
|
||||
@ -2,13 +2,6 @@
|
||||
Charm Stein Specifications
|
||||
===========================
|
||||
|
||||
Template:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Specification Template (Stein release) <template>
|
||||
|
||||
Stein implemented specs:
|
||||
|
||||
.. toctree::
|
||||
@ -24,11 +17,3 @@ Stein approved (but not implemented) specs:
|
||||
:maxdepth: 1
|
||||
|
||||
approved/*
|
||||
|
||||
Stein backlog (carried over from previous cycle) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
backlog/*
|
||||
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/train/approved
|
||||
@ -1 +0,0 @@
|
||||
../../../../specs/train/backlog
|
||||
@ -16,19 +16,3 @@ Train implemented specs:
|
||||
:maxdepth: 1
|
||||
|
||||
implemented/*
|
||||
|
||||
Train approved (but not implemented) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
approved/*
|
||||
|
||||
Train backlog (carried over from previous cycle) specs:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
backlog/*
|
||||
|
||||
@ -9,9 +9,9 @@ Template:
|
||||
|
||||
Specification Template (Ussuri release) <template>
|
||||
|
||||
Ussuri implemented specs:
|
||||
.. Ussuri implemented specs:
|
||||
|
||||
.. toctree::
|
||||
.. .. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
docutils!=0.13.1,>=0.11 # OSI-Approved Open Source, Public Domain
|
||||
oslosphinx>=4.7.0 # Apache-2.0
|
||||
pbr>=2.0.0,!=2.1.0 # Apache-2.0
|
||||
sphinx>=1.6.2,<2.0.0
|
||||
docutils!=0.13.1,>=0.11 # OSI-Approved Open Source, Public Domain
|
||||
openstackdocstheme>=1.31.2 # Apache-2.0
|
||||
sphinx>=1.6.2
|
||||
stestr>=2.0.0 # Apache-2.0
|
||||
testtools>=1.4.0 # MIT
|
||||
yasfb>=0.5.1
|
||||
|
||||
11
setup.cfg
11
setup.cfg
@ -10,14 +10,3 @@ classifier =
|
||||
Intended Audience :: Developers
|
||||
License :: OSI Approved :: Apache Software License
|
||||
Operating System :: POSIX :: Linux
|
||||
|
||||
[build_sphinx]
|
||||
all_files = 1
|
||||
build-dir = doc/build
|
||||
source-dir = doc/source
|
||||
|
||||
[pbr]
|
||||
warnerrors = True
|
||||
|
||||
[wheel]
|
||||
universal = 1
|
||||
|
||||
@ -52,8 +52,9 @@ Considerations for routed provider networks include:
|
||||
* live migration and evacutation of instances (constrain to the same L2);
|
||||
* DHCP and meta-data agent scheduling.
|
||||
|
||||
A `nova spec <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/neutron-routed-networks.html
|
||||
>`__ for routed provider networks contains a detailed overview of the
|
||||
A `nova spec
|
||||
<https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/neutron-routed-networks.html>`__
|
||||
for routed provider networks contains a detailed overview of the
|
||||
implemenation details to address the above points, including usage of
|
||||
`generic resource pools. <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/generic-resource-pools.html>`__
|
||||
|
||||
|
||||
@ -25,8 +25,8 @@ From `Fernet - Frequently Asked Questions
|
||||
|
||||
A fernet token is a bearer token that represents user authentication. Fernet
|
||||
tokens contain a limited amount of identity and authorization data in a
|
||||
`MessagePacked`__ payload. The payload is then wrapped as a Fernet message for
|
||||
transport, where `Fernet`__ provides the required web safe characteristics for
|
||||
`MessagePacked`_ payload. The payload is then wrapped as a Fernet message for
|
||||
transport, where `Fernet`_ provides the required web safe characteristics for
|
||||
use in URLs and headers. The data inside the fernet token is protected using
|
||||
symmetric encryption keys, or fernet keys.
|
||||
|
||||
|
||||
@ -86,7 +86,7 @@ does *not* do and lies outside of the scope of this spec.
|
||||
* It does not automatically advertise all OpenStack networks or whole subnet
|
||||
pools. A considerable amount of administrator configuration is still
|
||||
required, including associating OpenStack networks with the bgp-speaker. See
|
||||
the `Testing documentation https://docs.openstack.org/neutron-dynamic-routing/latest/contributor/testing.html>`__
|
||||
the `Testing documentation <https://docs.openstack.org/neutron-dynamic-routing/latest/contributor/testing.html>`__
|
||||
for a sense of the administrative overhead required.
|
||||
* It does not provide a mechanism for injecting arbitrary BGP routes (for
|
||||
example for /32 FIPs). It merely advertises OpenStack networks that have been
|
||||
|
||||
@ -85,7 +85,7 @@ The proposed change can be split to the following items:
|
||||
- "write-affinity-node-count":
|
||||
|
||||
purpose: specifies how many local objects will be tried before falling back
|
||||
to non-local ones
|
||||
to non-local ones
|
||||
data type: string
|
||||
valid values: matches "^\d+(\s\*\sreplicas)?$" pattern
|
||||
|
||||
|
||||
@ -102,7 +102,7 @@ Additional work:
|
||||
* Fix masakari-hostmonitors to work with pacemaker remote
|
||||
As mentioned masakari-hostmonitors does not work wih pacemaker-remote at the
|
||||
moment. A patch will need to be written to fix this and ideally landed
|
||||
upstream.
|
||||
upstream.
|
||||
|
||||
* Write maas stonith driver.
|
||||
It is important that instances that are using shared storage are only running
|
||||
|
||||
@ -42,7 +42,8 @@ Do it manually.
|
||||
Implementation
|
||||
==============
|
||||
|
||||
For each of the OpenStack charms that provides API, we need to do the following:
|
||||
For each of the OpenStack charms that provides API, we need to do the
|
||||
following:
|
||||
|
||||
* Add a configuration option to enable or disable audit middleware.
|
||||
* We need to add the specific sections that need to go into 3 files.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user