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

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

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

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

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 <http://wiki.qemu.org/ChangeLog/2.4>`__ so users
+`QEMU 2.4 - PowerPC <https://wiki.qemu.org/ChangeLog/2.4>`__ so users
 running instances on ppc64/ppc64le can choose one of the default
 created flavors as follows:
 

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

doc/source/guides/nova.rst

@@ -10,7 +10,7 @@ nova-serialproxy
 ================
 
 In Juno, nova implemented a `spec
-<http://specs.openstack.org/openstack/nova-specs/specs/juno/implemented/serial-ports.html>`_
+<https://specs.openstack.org/openstack/nova-specs/specs/juno/implemented/serial-ports.html>`_
 to allow read/write access to the serial console of an instance via
 `nova-serialproxy
 <https://docs.openstack.org/nova/latest/cli/nova-serialproxy.html>`_.
@@ -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
-<https://github.com/openstack/nova/blob/master/nova/conf/serial_console.py>`_.
+<https://opendev.org/openstack/nova/src/master/nova/conf/serial_console.py>`_.
 
 For more information on OpenStack configuration see the `OpenStack
 Compute Service Configuration Reference

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 <enable_logging>` of the stack
 output, then the stack output can be found in
 ``/var/log/cloud-init-output.log`` by default.
 

doc/source/plugins.rst

@@ -332,6 +332,6 @@ See Also
 ========
 
 For additional inspiration on devstack plugins you can check out the
-`Plugin Registry <plugin-registry.html>`_.
+:doc:`Plugin Registry <plugin-registry>`.
 
 .. _service types authority: https://specs.openstack.org/openstack/service-types-authority/

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

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 <https://docs.openstack.org/infra/zuul-jobs/roles.html#role-multi-node-bridge>`_.
+                                                              a dedicated `bridge role <https://zuul-ci.org/docs/zuul-jobs/general-roles.html#role-multi-node-bridge>`_.
 DEVSTACK_GATE_FEATURE_MATRIX                    devstack-gate ``test_matrix_features``
                                                               variable of the
                                                               test-matrix role in

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

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/

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