Merge "Update docs building"

.zuul.yaml

@@ -1,5 +1,7 @@
 - project:
     templates:
+      - publish-openstack-docs-pti
+      - build-release-notes-jobs-python3
       - openstack-cover-jobs
       - openstack-python-jobs
       - openstack-python3-train-jobs

README.md

@@ -1,15 +0,0 @@
-# Adjutant
-
-A basic workflow framework built using Django and Django-Rest-Framework to help automate basic Admin tasks within an OpenStack cluster.
-
-Primarily built as user registration service that fits into the OpenStack ecosystem alongside Keystone, its purpose to fill functionality missing from Keystone. Ultimately it is just a framework with actions that are tied to an endpoint and can require certain data fields and perform actions via the OpenStack clients as well as talk to external systems as needed.
-
-Useful for automating generic admin tasks that users might request but otherwise can't do without the admin role. Also allows automating the signup and creation of new users, but also allows such requests to require approval first if wanted. Due to issuing of uri+tokens for final steps of some actions, allows for a password submit/reset system as well.
-
-## Documentation:
-
-Documentation can be found at: https://adjutant.readthedocs.io/
-
-Documentation is stored in doc/, a sphinx build of the documentation can be generated with the command 'tox -e docs'.
-
-An API Reference is stored in api-ref. This is also a sphinx build and can be generated with 'tox -e api-ref'.

README.rst

@@ -0,0 +1,40 @@
+========================
+Team and repository tags
+========================
+
+.. image:: https://governance.openstack.org/tc/badges/adjutant.svg
+    :target: https://governance.openstack.org/tc/reference/tags/index.html
+
+.. Change things from this point on
+
+Adjutant
+========
+
+A basic workflow framework built using Django and
+Django-Rest-Framework to help automate basic Admin tasks within an
+OpenStack cluster.
+
+Primarily built as user registration service that fits into the
+OpenStack ecosystem alongside Keystone, its purpose to fill
+functionality missing from Keystone. Ultimately it is just a framework
+with actions that are tied to an endpoint and can require certain data
+fields and perform actions via the OpenStack clients as well as talk
+to external systems as needed.
+
+Useful for automating generic admin tasks that users might request but
+otherwise can't do without the admin role. Also allows automating the
+signup and creation of new users, but also allows such requests to
+require approval first if wanted. Due to issuing of uri+tokens for
+final steps of some actions, allows for a password submit/reset system
+as well.
+
+Documentation
+=============
+
+Documentation can be found at: https://docs.openstack.org/adjutant/latest
+
+Documentation is stored in doc/, a sphinx build of the documentation
+can be generated with the command `tox -e docs`.
+
+An API Reference is stored in api-ref. This is also a sphinx build and
+can be generated with `tox -e api-ref`.

api-ref/source/conf.py

@@ -30,26 +30,25 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.intersphinx',
     'os_api_ref',
     'openstackdocstheme'
 ]
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'openstackdocstheme'
 
 # 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
 # documentation.
 # html_theme_options = {}
 
+# openstackdocstheme settings
+repository_name = 'openstack/adjutant'
+html_theme = 'openstackdocs'
+use_storyboard = True
+
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
-
-repository_name = 'openstack/adjutant'
-bug_project = 'adjutant'
-bug_tag = ''
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -71,9 +70,9 @@ copyright = u'2017, Catalyst IT Ltd'
 # built documents.
 #
 # The short X.Y version.
-version = '1'
+version = ''
 # The full version, including alpha/beta/rc tags.
-release = '1'
+release = ''
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -147,7 +146,7 @@ pygments_style = 'sphinx'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

api-ref/source/index.rst

@@ -1,10 +1,6 @@
-.. Adjutant API Reference documentation master file, created by
+================================================
-   sphinx-quickstart on Wed Sep  6 13:55:48 2017.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to Adjutant API Reference documentation!
-==================================================
+================================================
 
 .. toctree::
    :maxdepth: 2

api-ref/source/parameters.yaml

@@ -43,18 +43,6 @@ filters:
     in: query
     required: false
     type: dictionary
-region:
-    description: |
-        Region to perform actions in.
-    in: query
-    required: true
-    type: string
-setup_network:
-    description: |
-        Whether or not to setup a default network for a new project
-    in: query
-    required: true
-    type: boolean
 page:
     description: |
         Page number to access, starts at and defaults to 1.
@@ -67,6 +55,18 @@ project_name:
     in: query
     required: true
     type: string
+region:
+    description: |
+        Region to perform actions in.
+    in: query
+    required: true
+    type: string
+setup_network:
+    description: |
+        Whether or not to setup a default network for a new project
+    in: query
+    required: true
+    type: boolean
 tasks_per_page:
     description: |
         Limit on the tasks viewed on each page.

api-ref/source/taskviews.inc

@@ -1,6 +1,6 @@
-************************************
+**********************************
 OpenStack Style TaskView Endpoints
-************************************
+**********************************
 
 A response of 'task created' means that the task requires admin approval and
 a response of 'created token' indicates that the task has been auto-approved

api-ref/source/v1-api-reference.rst

@@ -23,9 +23,9 @@ Tasks can bundle a number of actions and have 3 main steps.
 Depending on the task and the data provided some steps may be skipped.
 
 
-******************
+**************
 Authentication
-******************
+**************
 
 The 'X-Auth-Token' header value should be provided for authentication
 with a valid Keystone token.
@@ -58,7 +58,8 @@ Service Discovery
 ******************
 
 Version Discovery Endpoint
-===========================
+==========================
+
 .. rest_method::  GET /
 
 Unauthenticated.
@@ -83,9 +84,9 @@ Normal response code: 200
 .. include:: taskviews.inc
 
 
-************************************
+****************************
-Additional API Documentation:
+Additional API Documentation
-************************************
+****************************
 
 While in debug mode the service will supply online browsable documentation via
 Django REST Swagger.

doc/requirements.txt

@@ -0,0 +1,5 @@
+os-api-ref>=1.6.1 # Apache-2.0
+openstackdocstheme>=1.30.0  # Apache-2.0
+sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7'  # BSD
+sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4'  # BSD
+reno>=2.11.3 # Apache-2.0

doc/source/conf.py

@@ -30,11 +30,18 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['os_api_ref', ]
+extensions = [
+    'openstackdocstheme'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# openstackdocstheme settings
+repository_name = 'openstack/adjutant'
+html_theme = 'openstackdocs'
+use_storyboard = True
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
@@ -66,7 +73,7 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
@@ -80,7 +87,7 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ------------------------------------------
@@ -91,24 +98,6 @@ htmlhelp_basename = 'Adjutantdoc'
 
 # -- 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': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).

doc/source/devstack-guide.rst

@@ -14,7 +14,7 @@ Deploy Devstack
 
 Grab the Devstack repo::
 
-    git clone https://github.com/openstack-dev/devstack.git
+    git clone https://opendev.org/openstack/devstack
 
 
 And then define a basic localrc file with the password set and place that in
@@ -41,7 +41,7 @@ Deploy Adjutant
 
 Grab the Adjutant repo::
 
-    git clone https://github.com/openstack/adjutant.git
+    git clone https://opendev.org/openstack/adjutant
 
 Then you'll want to setup a virtual environment::
 
@@ -236,7 +236,7 @@ id you can see some details about it::
 Setting Up Adjutant on Horizon
 **********************************
 Adjutant has a Horizon UI plugin, the code and setup instructions for it can
-be found `here <https://github.com/openstack/adjutant-ui>`_
+be found `here <https://opendev.org/openstack/adjutant-ui>`_.
 
 If you do set this up, you will want to edit the default Adjutant conf to so
 that the TOKEN_SUBMISSION_URL is correctly set to point at your Horizon.

doc/source/index.rst

@@ -15,9 +15,6 @@ Welcome to Adjutant's documentation!
    features
    history
 
-   .. standard task views and actions
-
-
 A basic workflow framework built using Django and Django-Rest-Framework to
 help automate Admin tasks within an OpenStack cluster.
 
@@ -41,22 +38,23 @@ The command ``tox -e venv {your commands}`` can be used and will setup a
 virtual environment with all the required dependencies for you.
 
 For example, running the server on port 5050 can be done with::
+
   tox -e venv adjutant-api runserver 0.0.0.0:5050
 
 
-************************
+***********************
 Client and UI Libraries
-************************
+***********************
 
 Both a commandline/python and a horizon plugin exist for adjutant:
 
-* `python-adjutantclient <https://github.com/openstack/python-adjutantclient>`_
+* `python-adjutantclient <https://opendev.org/openstack/python-adjutantclient>`_
-* `adjutant-ui <https://github.com/openstack/adjutant-ui>`_
+* `adjutant-ui <https://opendev.org/openstack/adjutant-ui>`_
 
 
-************************
+***********************
 Tests and Documentation
-************************
+***********************
 
 Tests and documentation are managed by tox, they can be run simply with the
 command ``tox``.
@@ -77,13 +75,13 @@ the command ``tox -e docs``, these will be placed inside the ``doc/build``
 directory.
 
 
-************************
+************
 Contributing
-************************
+************
 
 Bugs and blueprints for Adjutant, its ui and client are managed `here on
 launchpad. <https://launchpad.net/adjutant>`_
 
 Changes should be submitted through the OpenStack gerrit, the guide for
 contributing to OpenStack projects is
-`here <https://docs.openstack.org/contributor-guide/>`_ .
+`here <https://docs.openstack.org/contributor/>`_ .

doc/source/release-notes.rst

@@ -96,4 +96,5 @@ note. We can iterate on the content and application of the release note during
 the review process.
 
 For more information on how and when to create release notes, see the
-`project-team-guide <https://docs.openstack.org/project-team-guide/release-management.html#how-to-add-new-release-notes>`_.
+`project-team-guide
+<https://docs.openstack.org/project-team-guide/release-management.html#how-to-add-new-release-notes>`_.

package_readme.rst

@@ -1,19 +1,32 @@
-Adjutant is a service that sits along Keystone and allows the automation and approval of tasks normally requiring a user with an admin role. Adjutant allows defining of such tasks as part of a workflow which can either be entirely automatic, or require admin approval. The goal is to automate business logic, and augment the functionality of Keystone and other OpenStack services without getting in the way of future OpenStack features or duplicating development effort.
+Adjutant is a service that sits along Keystone and allows the
+automation and approval of tasks normally requiring a user with an
+admin role. Adjutant allows defining of such tasks as part of a
+workflow which can either be entirely automatic, or require admin
+approval. The goal is to automate business logic, and augment the
+functionality of Keystone and other OpenStack services without getting
+in the way of future OpenStack features or duplicating development
+effort.
 
 Quick Dev Deployment
 ====================
 
-To quickly deploy the service for testing you can install via pip, setup a default config file, and then run the test Django server.
+To quickly deploy the service for testing you can install via pip,
+setup a default config file, and then run the test Django server.
 
 ::
 
     pip install adjutant
 
-Then running the service will look for a config in either **/etc/adjutant/conf.yaml** or it will default to **conf/conf.yaml** from the directory you run the command in.
+Then running the service will look for a config in either
+**/etc/adjutant/conf.yaml** or it will default to **conf/conf.yaml**
+from the directory you run the command in.
 
 ::
 
     adjutant migrate
     adjutant runserver <port>
 
-For now you will have to source the default conf from the github repo or the library install location itself, but we hope to add an additional commandline function which will copy and setup a basic default config in **/etc/adjutant/conf.yaml**.
+For now you will have to source the default conf from the github repo
+or the library install location itself, but we hope to add an
+additional commandline function which will copy and setup a basic
+default config in **/etc/adjutant/conf.yaml**.

releasenotes/source/conf.py

@@ -54,6 +54,10 @@ master_doc = 'index'
 project = u'Adjutant Release Notes'
 copyright = u'2019, Adjutant Developers'
 
+# openstackdocstheme settings
+repository_name = 'openstack/adjutant'
+use_storyboard = True
+
 # Release  notes are version independent
 
 # The full version, including alpha/beta/rc tags.
@@ -134,7 +138,7 @@ html_theme = 'openstackdocs'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -144,7 +148,7 @@ html_static_path = ['_static']
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 # html_last_updated_fmt = '%b %d, %Y'
-html_last_updated_fmt = '%Y-%m-%d %H:%M'
+# html_last_updated_fmt = '%Y-%m-%d %H:%M'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -189,17 +193,6 @@ htmlhelp_basename = 'AdjutantReleaseNotesdoc'
 
 # -- 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, or own class]).
@@ -269,8 +262,3 @@ texinfo_documents = [
 
 # -- Options for Internationalization output ------------------------------
 locale_dirs = ['locale/']
-
-# -- Options for openstackdocstheme -------------------------------------------
-repository_name = 'openstack/adjutant'
-bug_project = 'adjutant'
-bug_tag = 'doc'

setup.cfg

@@ -8,7 +8,7 @@ description-content-type = text/x-rst; charset=UTF-8
 home-page = https://opendev.org/openstack/adjutant
 project_urls =
     Bug Tracker = https://storyboard.openstack.org/#!/project/openstack/adjutant
-    Documentation = https://adjutant.readthedocs.io/en/latest/
+    Documentation = https://docs.openstack.org/adjutant/latest/
     Source Code = https://opendev.org/openstack/adjutant
 license = Apache-2
 classifier =
@@ -35,13 +35,6 @@ keywords =
 packages =
     adjutant
 
-[build_sphinx]
-builders = html, man
-source-dir = doc/source
-build-dir = doc/build
-all-files = 1
-warning-is-error = 1
-
 [entry_points]
 console_scripts =
     adjutant-api = adjutant:management_command

test-requirements.txt

@@ -2,12 +2,9 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
-coverage>=4.5.3
+flake8>=3.7.7 # MIT
-doc8>=0.8.0
+
-flake8>=3.7.7
+coverage>=4.5.3 # Apache-2.0
-mock>=3.0.5
+doc8>=0.8.0 # Apache-2.0
-os-api-ref>=1.6.1 # Apache-2.0
+mock>=3.0.0 # BSD
-sphinx-rtd-theme>=0.4.3
+Pygments>=2.2.0 # BSD license
-sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7'  # BSD
-sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4'  # BSD
-reno>=2.11.3 # Apache-2.0

tox.ini

@@ -11,7 +11,9 @@ setenv = VIRTUAL_ENV={envdir}
 
 [testenv:pep8]
 basepython = python3
-commands = flake8
+commands =
+    flake8
+    doc8
 
 [testenv:cover]
 basepython = python3
@@ -32,16 +34,20 @@ commands = {posargs}
 
 [testenv:docs]
 basepython = python3
+deps = -r{toxinidir}/doc/requirements.txt
 commands =
-    doc8 doc/source
+    sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html
-    python setup.py build_sphinx
 
 [testenv:api-ref]
 basepython = python3
+deps = {[testenv:docs]deps}
 commands =
-    doc8 api-ref/source
+    sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
-    python setup.py build_sphinx -s api-ref/source/ --build-dir api-ref/build/
 
+[testenv:releasenotes]
+basepython = python3
+deps = {[testenv:docs]deps}
+commands = sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
 [flake8]
 ignore = D100,D101,D102,D103,D104,D105,D200,D203,D202,D204,D205,D208,D400,D401,W503
@@ -49,5 +55,6 @@ show-source = true
 builtins = _
 exclude=.venv,venv,.env,env,.git,.tox,dist,doc,*lib/python*,*egg,releasenotes,adjutant/api/migrations/*,adjutant/actions/migrations
 
-[testenv:releasenotes]
+[doc8]
-commands = sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
+ignore-path=.tox,*.egg-info,doc/build,.eggs/*/EGG-INFO/*.txt,./*.txt,adjutant
+extension=.txt,.rst,.inc