From 8dd89e52d04da2230914deceaee7c4d41e73ccc2 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sun, 11 Aug 2019 16:00:12 +0200 Subject: [PATCH] Update docs building Switch to "modern" way of building docs using sphinx-build directly, remove now unsed parts from setup.cfg. Upgrade to openstackdocstheme 1.20 and remove obsolete variables from conf.py. Convert external links to internal RST links so that Sphinx can verify that they are correct. Replace redirected links with new targets. Use opendev.org instead of github.com where appropriate. Change-Id: Iedcc008b170821aa74acefc02ec6a243a0dc307c --- HACKING.rst | 2 +- doc/requirements.txt | 2 +- doc/source/conf.py | 26 ++++---------------- doc/source/configuration.rst | 4 ++- doc/source/guides/devstack-with-lbaas-v2.rst | 2 +- doc/source/guides/nova.rst | 4 +-- doc/source/guides/single-vm.rst | 2 +- doc/source/plugins.rst | 2 +- doc/source/systemd.rst | 2 +- doc/source/zuul_ci_jobs_migration.rst | 2 +- setup.cfg | 9 ------- tools/xen/README.md | 2 +- tox.ini | 3 ++- 13 files changed, 20 insertions(+), 42 deletions(-) diff --git a/HACKING.rst b/HACKING.rst index f6951064ae..f0bb269cb3 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -189,7 +189,7 @@ to enforce basic guidelines, similar to pep8 and flake8 tools for Python. The list below is not complete for what bashate checks, nor is it all checked by bashate. So many lines of code, so little time. -.. _bashate: https://pypi.python.org/pypi/bashate +.. _bashate: https://pypi.org/project/bashate/ Whitespace Rules ---------------- diff --git a/doc/requirements.txt b/doc/requirements.txt index f65e9dfece..fffb83d96b 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -3,7 +3,7 @@ pbr>=2.0.0,!=2.1.0 Pygments docutils sphinx>=1.6.2 -openstackdocstheme>=1.11.0 +openstackdocstheme>=1.20.0 nwdiag blockdiag sphinxcontrib-blockdiag diff --git a/doc/source/conf.py b/doc/source/conf.py index e9708fae1d..9059f8c678 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -11,9 +11,6 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys -import os - # 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 # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -26,13 +23,16 @@ import os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ 'sphinx.ext.autodoc', 'zuul_sphinx', 'openstackdocstheme', 'sphinxcontrib.blockdiag', 'sphinxcontrib.nwdiag' ] +extensions = [ 'sphinx.ext.autodoc', + 'zuul_sphinx', + 'openstackdocstheme', + 'sphinxcontrib.blockdiag', + 'sphinxcontrib.nwdiag' ] # openstackdocstheme options repository_name = 'openstack-dev/devstack' bug_project = 'devstack' bug_tag = '' -html_last_updated_fmt = '%Y-%m-%d %H:%M' todo_include_todos = True @@ -119,11 +119,6 @@ html_theme = 'openstackdocs' # 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 @@ -167,17 +162,6 @@ htmlhelp_basename = 'DevStack-doc' # -- 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 = [ diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 0105d5e636..45f4ffe6e9 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -259,6 +259,8 @@ changed from the default value. Logging ------- +.. _enable_logging: + Enable Logging ~~~~~~~~~~~~~~ @@ -495,7 +497,7 @@ should be specified in the configuration file so Tempest selects the default flavors instead. KVM on Power with QEMU 2.4 requires 512 MB to load the firmware - -`QEMU 2.4 - PowerPC `__ so users +`QEMU 2.4 - PowerPC `__ so users running instances on ppc64/ppc64le can choose one of the default created flavors as follows: diff --git a/doc/source/guides/devstack-with-lbaas-v2.rst b/doc/source/guides/devstack-with-lbaas-v2.rst index 1cd85b4de9..669a70d0bb 100644 --- a/doc/source/guides/devstack-with-lbaas-v2.rst +++ b/doc/source/guides/devstack-with-lbaas-v2.rst @@ -39,7 +39,7 @@ Edit your ``/opt/stack/devstack/local.conf`` to look like # If you are enabling horizon, include the octavia dashboard # enable_plugin octavia-dashboard https://opendev.org/openstack/octavia-dashboard.git # If you are enabling barbican for TLS offload in Octavia, include it here. - # enable_plugin barbican https://github.com/openstack/barbican.git + # enable_plugin barbican https://opendev.org/openstack/barbican # If you have python3 available: # USE_PYTHON3=True diff --git a/doc/source/guides/nova.rst b/doc/source/guides/nova.rst index 2271e2321b..5b427972c4 100644 --- a/doc/source/guides/nova.rst +++ b/doc/source/guides/nova.rst @@ -10,7 +10,7 @@ nova-serialproxy ================ In Juno, nova implemented a `spec -`_ +`_ to allow read/write access to the serial console of an instance via `nova-serialproxy `_. @@ -63,7 +63,7 @@ The service can be enabled by adding ``n-sproxy`` to Enabling the service is enough to be functional for a single machine DevStack. These config options are defined in `nova.conf.serial_console -`_. +`_. For more information on OpenStack configuration see the `OpenStack Compute Service Configuration Reference diff --git a/doc/source/guides/single-vm.rst b/doc/source/guides/single-vm.rst index 8ebf2a638d..7dac18b333 100644 --- a/doc/source/guides/single-vm.rst +++ b/doc/source/guides/single-vm.rst @@ -78,7 +78,7 @@ As DevStack will refuse to run as root, this configures ``cloud-init`` to create a non-root user and run the ``start.sh`` script as that user. If you are using cloud-init and you have not -`enabled custom logging <../configuration.html#enable-logging>`_ of the stack +:ref:`enabled custom logging ` of the stack output, then the stack output can be found in ``/var/log/cloud-init-output.log`` by default. diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst index 2484569d35..a18a786c49 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -332,6 +332,6 @@ See Also ======== For additional inspiration on devstack plugins you can check out the -`Plugin Registry `_. +:doc:`Plugin Registry `. .. _service types authority: https://specs.openstack.org/openstack/service-types-authority/ diff --git a/doc/source/systemd.rst b/doc/source/systemd.rst index 1bc9911879..15b3f75660 100644 --- a/doc/source/systemd.rst +++ b/doc/source/systemd.rst @@ -194,7 +194,7 @@ Telnet to that port to enter the pdb session:: See the `remote-pdb`_ home page for more options. -.. _`remote-pdb`: https://pypi.python.org/pypi/remote-pdb +.. _`remote-pdb`: https://pypi.org/project/remote-pdb/ Known Issues ============ diff --git a/doc/source/zuul_ci_jobs_migration.rst b/doc/source/zuul_ci_jobs_migration.rst index dbb79893db..ed97d4cf34 100644 --- a/doc/source/zuul_ci_jobs_migration.rst +++ b/doc/source/zuul_ci_jobs_migration.rst @@ -190,7 +190,7 @@ DEVSTACK_GATE_NET_OVERLAY zuul-jobs A bridge called br-infra is set up for all jobs that inherit from multinode with - a dedicated `bridge role `_. + a dedicated `bridge role `_. DEVSTACK_GATE_FEATURE_MATRIX devstack-gate ``test_matrix_features`` variable of the test-matrix role in diff --git a/setup.cfg b/setup.cfg index 825d386026..4e27ad80d8 100644 --- a/setup.cfg +++ b/setup.cfg @@ -11,14 +11,5 @@ classifier = License :: OSI Approved :: Apache Software License Operating System :: POSIX :: Linux -[build_sphinx] -all_files = 1 -build-dir = doc/build -source-dir = doc/source -warning-is-error = 1 - -[pbr] -warnerrors = True - [wheel] universal = 1 diff --git a/tools/xen/README.md b/tools/xen/README.md index 22263bb074..287301156e 100644 --- a/tools/xen/README.md +++ b/tools/xen/README.md @@ -1,3 +1,3 @@ Note: XenServer relative tools have been moved to `os-xenapi`_ and be maintained there. -.. _os-xenapi: https://github.com/openstack/os-xenapi/ +.. _os-xenapi: https://opendev.org/x/os-xenapi/ diff --git a/tox.ini b/tox.ini index f643fdb930..d81107fe1a 100644 --- a/tox.ini +++ b/tox.ini @@ -41,7 +41,8 @@ whitelist_externals = bash setenv = TOP_DIR={toxinidir} commands = - python setup.py build_sphinx + sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html + [testenv:venv] basepython = python3