From 46fa54dd05ac0b98bb097e12e9dfc7b90e263d23 Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Mon, 27 Nov 2017 16:56:02 -0500 Subject: [PATCH] Update glance-specs to use openstackdocstheme Maintenance on oslosphinx ended with the Pike release. This patch includes the following changes: * switch to openstackdocstheme * set context options for openstackdocstheme - glance-specs doesn't have its own bug tracker, so config to create bugs in the glance bug tracker with tag 'glance-specs' * update requirements file * update setup.cfg to use warning-is-error * update four specs whose warnings were previously ignored * add an '_extra' directory with stub .htaccess file * configure docs build to include '_extra' * update build command in tox.ini Change-Id: I4da477fd39685a22fb4ef9d702af9b9a79bda0c2 --- doc/source/_extra/.htaccess | 2 ++ doc/source/conf.py | 18 +++++++++++++++--- requirements.txt | 6 +++--- setup.cfg | 5 ++--- .../image-import/image-import-refactor.rst | 15 +++++++++++---- .../approved/glance/deprecate-registry.rst | 4 ++-- .../database-strategy-for-rolling-upgrades.rst | 1 - .../untargeted/glance/duplicate-downloads.rst | 2 +- tox.ini | 6 +++++- 9 files changed, 41 insertions(+), 18 deletions(-) create mode 100644 doc/source/_extra/.htaccess diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess new file mode 100644 index 00000000..758db41b --- /dev/null +++ b/doc/source/_extra/.htaccess @@ -0,0 +1,2 @@ +# This file contains redirects to handle existing URLs for specs that +# have been moved diff --git a/doc/source/conf.py b/doc/source/conf.py index 90267703..74360bc1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -16,6 +16,8 @@ import subprocess import sys import os +import openstackdocstheme + # 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. @@ -35,10 +37,15 @@ extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.actdiag', 'sphinxcontrib.seqdiag', 'sphinxcontrib.nwdiag', - 'oslosphinx', + 'openstackdocstheme', 'yasfb', ] +# config for openstackdocstheme +repository_name = 'openstack/glance-specs' +bug_project = 'glance' +bug_tag = 'glance-specs' + # Feed configuration for yasfb feed_base_url = 'http://specs.openstack.org/openstack/glance-specs' feed_author = 'OpenStack Glance Team' @@ -106,7 +113,7 @@ man_pages = [] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -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 @@ -114,7 +121,7 @@ html_theme = 'nature' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +#html_theme_path = [openstackdocstheme.get_html_theme_path()] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -149,6 +156,10 @@ html_last_updated_fmt = subprocess.check_output(git_cmd).decode('utf-8') # template names. #html_additional_pages = {} +# Add any paths that contain "extra" files, such as .htaccess or +# robots.txt. +html_extra_path = ['_extra'] + # If false, no module index is generated. html_domain_indices = False @@ -178,6 +189,7 @@ html_use_index = False # Output file base name for HTML help builder. htmlhelp_basename = 'Glance-Specsdoc' +html_last_updated_fmt = '%Y-%m-%d %H:%M' # -- Options for LaTeX output -------------------------------------------------- diff --git a/requirements.txt b/requirements.txt index 3af565a7..7f29d0cc 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,10 +1,10 @@ actdiag blockdiag nwdiag -oslosphinx -pbr>=0.6,<1.0 +openstackdocstheme>=1.17.0 # Apache-2.0 +pbr>=1.8 # Apache-2.0 seqdiag -sphinx>=1.1.2,<1.2 +sphinx>=1.6.2 # BSD sphinxcontrib-actdiag sphinxcontrib-blockdiag sphinxcontrib-nwdiag diff --git a/setup.cfg b/setup.cfg index 45ab013c..405e82a1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -12,12 +12,11 @@ classifier = Operating System :: POSIX :: Linux [build_sphinx] +builders = html all_files = 1 build-dir = doc/build source-dir = doc/source - -[pbr] -warnerrors = True +warning-is-error = 1 [wheel] universal = 1 diff --git a/specs/mitaka/approved/image-import/image-import-refactor.rst b/specs/mitaka/approved/image-import/image-import-refactor.rst index cd5669b2..fe130763 100644 --- a/specs/mitaka/approved/image-import/image-import-refactor.rst +++ b/specs/mitaka/approved/image-import/image-import-refactor.rst @@ -1216,14 +1216,11 @@ Everything you always wanted to know about Glance Image Import but were afraid t References ========== -.. [OSB1] https://blueprints.launchpad.net/glance/+spec/upload-download-workflow .. [OSD1] http://developer.openstack.org/api-ref-image-v2.html#os-tasks-v2 .. [OSE1] https://etherpad.openstack.org/p/havana-getting-glance-ready-for-public-clouds .. [OSE2] https://etherpad.openstack.org/p/glance-upload-mechanism-reloaded .. [OSE3] https://etherpad.openstack.org/p/Mitaka-glance-image-import-reloaded .. [OSE4] https://etherpad.openstack.org/p/glance-image-import-example -.. [OSG1] https://review.openstack.org/#/c/220166/ -.. [OSG2] https://review.openstack.org/#/c/220166/4/doc/source/tasks.rst .. [OSL1] http://eavesdrop.openstack.org/irclogs/%23openstack-glance/%23openstack-glance.2015-09-22.log.html#t2015-09-22T14:31:00 .. [OSM1] http://lists.openstack.org/pipermail/openstack-dev/2015-September/thread.html#74360 .. [OSM2] http://lists.openstack.org/pipermail/openstack-dev/2015-September/thread.html#74383 @@ -1232,6 +1229,16 @@ References .. [OSW1] https://wiki.openstack.org/wiki/Glance-tasks-api .. [OSW2] https://wiki.openstack.org/wiki/Glance-tasks-api-product .. [OSW3] https://wiki.openstack.org/wiki/Glance-tasks-import -.. [OSW4] https://wiki.openstack.org/wiki/Glance-upload-mechanism-reloaded .. [NEW1] https://governance.openstack.org/resolutions/20151211-bring-your-own-kernel.html .. [NEW2] https://github.com/openstack/defcore/commit/10562c245a6332f52cb5c5d15739dfab15b2baa6 + +Other Relevant Supporting Information +===================================== + +[OSB1] https://blueprints.launchpad.net/glance/+spec/upload-download-workflow + +[OSG1] https://review.openstack.org/#/c/220166/ + +[OSG2] https://review.openstack.org/#/c/220166/4/doc/source/tasks.rst + +[OSW4] https://wiki.openstack.org/wiki/Glance-upload-mechanism-reloaded diff --git a/specs/newton/approved/glance/deprecate-registry.rst b/specs/newton/approved/glance/deprecate-registry.rst index 89fcc75d..9b0bb225 100644 --- a/specs/newton/approved/glance/deprecate-registry.rst +++ b/specs/newton/approved/glance/deprecate-registry.rst @@ -36,13 +36,13 @@ another set of API nodes that need to be deployed, monitored, and upgraded. From a documentation stand point, the team needs to make sure the service docs are up-to-date, the best practices are spelled out and configuration files updated. -The benefits of this service have been discussed in a recent thread[0]_ on both, +The benefits of this service have been discussed in a recent thread [0]_ on both developers and operators, mailing lists. The output of this thread is not really conclusive, although it suggests there's no real use case for this service anymore and that OPs would be better off by not having it. Rolling upgrades was brought as a possible blocker for this deprecation. As it's -been explained in the thread[1], upgrading Glance (or even the planned work on +been explained in the thread [1]_, upgrading Glance (or even the planned work on rolling upgrades) should not depend on the presence of this service. Anything needed from Glance Registry should be possible to obtain from Glance API itself. diff --git a/specs/ocata/implemented/glance/database-strategy-for-rolling-upgrades.rst b/specs/ocata/implemented/glance/database-strategy-for-rolling-upgrades.rst index 3909b272..f4aa275e 100644 --- a/specs/ocata/implemented/glance/database-strategy-for-rolling-upgrades.rst +++ b/specs/ocata/implemented/glance/database-strategy-for-rolling-upgrades.rst @@ -801,7 +801,6 @@ References .. [GVV1] https://governance.openstack.org/reference/tags/assert_supports-rolling-upgrade.html .. [GVV2] https://governance.openstack.org/reference/tags/assert_supports-zero-downtime-upgrade.html -.. [GVV3] https://governance.openstack.org/reference/tags/assert_supports-zero-impact-upgrade.html .. [NOV1] http://www.danplanet.com/blog/2015/10/07/upgrades-in-nova-database-migrations/ .. [CIN1] https://specs.openstack.org/openstack/cinder-specs/specs/mitaka/online-schema-upgrades.html .. [KEY1] https://specs.openstack.org/openstack/keystone-specs/specs/mitaka/online-schema-migration.html diff --git a/specs/untargeted/glance/duplicate-downloads.rst b/specs/untargeted/glance/duplicate-downloads.rst index 23c34560..558a2658 100644 --- a/specs/untargeted/glance/duplicate-downloads.rst +++ b/specs/untargeted/glance/duplicate-downloads.rst @@ -108,7 +108,7 @@ whether the image was already cached when the request was received. While the exact mechanism for achieving this might vary, one example of how this can be achieved follows: -.. code-block:: python +.. code-block:: none if the cache file does not exist: create it diff --git a/tox.ini b/tox.ini index b92724b3..5334704f 100644 --- a/tox.ini +++ b/tox.ini @@ -14,4 +14,8 @@ commands = python setup.py testr --slowest --testr-args='{posargs}' commands = {posargs} [testenv:docs] -commands = python setup.py build_sphinx +whitelist_externals = + rm +commands = + rm -rf doc/build + python setup.py build_sphinx