From b8cfb53f19fae9031872ddbfe383ceee77334763 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Thu, 4 Jun 2020 13:29:55 +0200 Subject: [PATCH] Update docs building Several reorgs: * setup.cfg/setup.py must be in top-level dir so that siblings (installing for example openstackdocstheme from source instead of pip) works. * Update openstackdocstheme version (see below) * Remove unused entries from setup.cfg * Remove py27 code from setup.py * Update tox.ini for a py3 only world and cleanup Switch to openstackdocstheme 2.2.1 version. Using this version will allow especially: * Linking from HTML to PDF document * Allow parallel building of documents * Fix some rendering problems Update Sphinx version as well. Disable openstackdocs_auto_name to use 'project' variable as name. Change pygments_style to 'native' since old theme version always used 'native' and the theme now respects the setting and using 'sphinx' can lead to some strange rendering. openstackdocstheme renames some variables, so follow the renames before the next release removes them. A couple of variables are also not needed anymore, remove them. See also http://lists.openstack.org/pipermail/openstack-discuss/2020-May/014971.html Change-Id: I27039f9dc52c3e6c9e667b5699172d0f834e8f6b --- api-ref/source/conf.py | 11 ++++++----- doc/requirements.txt | 7 +++---- doc/source/conf.py | 19 ++++++------------- doc/setup.cfg => setup.cfg | 18 +----------------- doc/setup.py => setup.py | 9 --------- tox.ini | 11 +++-------- 6 files changed, 19 insertions(+), 56 deletions(-) rename doc/setup.cfg => setup.cfg (66%) rename doc/setup.py => setup.py (66%) diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py index 0861f2520..83ed1b2d1 100644 --- a/api-ref/source/conf.py +++ b/api-ref/source/conf.py @@ -41,10 +41,11 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -repository_name = 'openstack/stx-docs' -project = u'StarlingX' -bug_project = 'starlingx' -bug_tag = 'stx.docs' +openstackdocs_repo_name = 'openstack/stx-docs' +openstackdocs_project = 'StarlingX' +openstackdocs_auto_name = False +openstackdocs_bug_project = 'starlingx' +openstackdocs_bug_tag = 'stx.docs' # If true, the current module name will be prepended to all description # unit titles (such as .. function::). @@ -55,7 +56,7 @@ add_module_names = False show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'native' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass diff --git a/doc/requirements.txt b/doc/requirements.txt index fbb0f2689..66cd83899 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,5 @@ -openstack-doc-tools>=1.6.0 -sphinx>=1.6.2 -openstackdocstheme>=1.26.0 # Apache-2.0 +sphinx>=2.0.0,!=2.1.0 +openstackdocstheme>=2.2.1 # Apache-2.0 # API Reference Guide -os-api-ref>=1.4.0 # Apache-2.0 +os-api-ref>=1.5.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index e45280617..5df10dc25 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -6,8 +6,6 @@ # full list see the documentation: # http://www.sphinx-doc.org/en/master/config -import pbr.version - # -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, @@ -25,17 +23,6 @@ project = u'StarlingX' copyright = '2018, StarlingX' author = 'StarlingX' -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -version_info = pbr.version.VersionInfo('python-openstackclient') - -# The short X.Y version. -version = '' -# The full version, including alpha/beta/rc tags. -release = '' - # -- General configuration --------------------------------------------------- @@ -77,6 +64,12 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# General information about the project. +openstackdocs_repo_name = 'openstack/stx-docs' +openstackdocs_project = 'StarlingX' +openstackdocs_auto_name = False +openstackdocs_bug_project = 'starlingx' +openstackdocs_bug_tag = 'stx.docs' # -- Options for HTML output ------------------------------------------------- diff --git a/doc/setup.cfg b/setup.cfg similarity index 66% rename from doc/setup.cfg rename to setup.cfg index 43ae0004e..1ff59231c 100644 --- a/doc/setup.cfg +++ b/setup.cfg @@ -1,5 +1,6 @@ [metadata] summary = StarlingX Documentation +name = docs author = StarlingX author-email = starlingx-discuss@lists.starlingx.io home-page = https://starlingx.io @@ -9,20 +10,3 @@ Intended Audience :: Information Technology License :: OSI Approved :: Apache Software License Operating System :: POSIX :: Linux Topic :: Documentation - -[global] -setup-hooks = - pbr.hooks.setup_hook - -[files] - -[build_sphinx] -all_files = 1 -build-dir = build -source-dir = source - -[wheel] -universal = 1 - -[pbr] -warnerrors = True diff --git a/doc/setup.py b/setup.py similarity index 66% rename from doc/setup.py rename to setup.py index 62f38a592..186fa00c8 100644 --- a/doc/setup.py +++ b/setup.py @@ -13,17 +13,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT import setuptools -# In python < 2.7.4, a lazy loading of package `pbr` will break -# setuptools if some other modules registered functions in `atexit`. -# solution from: http://bugs.python.org/issue15881#msg170215 -try: - import multiprocessing # noqa -except ImportError: - pass - setuptools.setup( setup_requires=['pbr'], pbr=True) diff --git a/tox.ini b/tox.ini index 1c6532f1c..88eb81073 100644 --- a/tox.ini +++ b/tox.ini @@ -4,7 +4,7 @@ minversion = 2.3 skipsdist = True [testenv] -install_command = pip install -U {opts} {packages} +basepython = python3 setenv = VIRTUAL_ENV={envdir} OS_STDOUT_CAPTURE=1 OS_STDERR_CAPTURE=1 @@ -12,24 +12,20 @@ setenv = VIRTUAL_ENV={envdir} deps = -r{toxinidir}/test-requirements.txt [testenv:docs] -basepython = python3 deps = - -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt} + -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} -r{toxinidir}/doc/requirements.txt commands = sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html [testenv:api-ref] -basepython = python3 -deps = - -r{toxinidir}/doc/requirements.txt +deps = {[testenv:docs]deps} commands = rm -rf api-ref/build sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html whitelist_externals = rm [testenv:linters] -basepython = python3 whitelist_externals = bash commands = bash -c "find {toxinidir} \ @@ -38,5 +34,4 @@ commands = -print0 | xargs -0 yamllint" [testenv:venv] -basepython = python3 commands = {posargs}