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 2020-02-23 14:25:54 +01:00
parent 958a432bca
commit 77dfcdd291
28 changed files with 31 additions and 184 deletions

View File

@ -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 = [

View File

@ -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
=======

View File

@ -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')

View File

@ -1 +0,0 @@
../../../../specs/newton/approved/

View File

@ -16,11 +16,3 @@ Newton implemented specs:
:maxdepth: 1
implemented/*
Newton approved (but not implemented) specs:
.. toctree::
:glob:
:maxdepth: 1
approved/*

View File

@ -1 +0,0 @@
../../../../specs/ocata/approved

View File

@ -1 +0,0 @@
../../../../specs/ocata/backlog

View File

@ -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/*

View File

@ -1 +0,0 @@
../../../../specs/pike/approved

View File

@ -1 +0,0 @@
../../../../specs/pike/backlog

View File

@ -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/*

View File

@ -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/*

View File

@ -2,13 +2,6 @@
Charm Rocky Specifications
===========================
Template:
.. toctree::
:maxdepth: 1
Specification Template (Rocky release) <template>
Rocky implemented specs:
.. toctree::

View File

@ -1 +0,0 @@
../../../../specs/stein/backlog

View File

@ -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/*

View File

@ -1 +0,0 @@
../../../../specs/train/approved

View File

@ -1 +0,0 @@
../../../../specs/train/backlog

View File

@ -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/*

View File

@ -9,9 +9,9 @@ Template:
Specification Template (Ussuri release) <template>
Ussuri implemented specs:
.. Ussuri implemented specs:
.. toctree::
.. .. toctree::
:glob:
:maxdepth: 1

View File

@ -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

View File

@ -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

View File

@ -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>`__

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -29,8 +29,7 @@ commands = {posargs}
[testenv:docs]
basepython = python3
commands =
find . -type f -name "*.py[c|o]" -delete
python setup.py build_sphinx
sphinx-build -b html -W doc/source doc/build/html
[testenv:pep8]
basepython = python3