Merge "Update docs building"

This commit is contained in:
Zuul 2019-08-27 23:39:18 +00:00 committed by Gerrit Code Review
commit fac939b6e6
22 changed files with 151 additions and 137 deletions

View File

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

View File

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

40
README.rst Normal file
View File

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

View File

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

View File

@ -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! Welcome to Adjutant API Reference documentation!
================================================== ================================================
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

View File

@ -43,18 +43,6 @@ filters:
in: query in: query
required: false required: false
type: dictionary 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: page:
description: | description: |
Page number to access, starts at and defaults to 1. Page number to access, starts at and defaults to 1.
@ -67,6 +55,18 @@ project_name:
in: query in: query
required: true required: true
type: string 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: tasks_per_page:
description: | description: |
Limit on the tasks viewed on each page. Limit on the tasks viewed on each page.

View File

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

View File

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

5
doc/requirements.txt Normal file
View File

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

View File

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

View File

@ -14,7 +14,7 @@ Deploy Devstack
Grab the Devstack repo:: 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 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:: 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:: 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 Setting Up Adjutant on Horizon
********************************** **********************************
Adjutant has a Horizon UI plugin, the code and setup instructions for it can 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 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. that the TOKEN_SUBMISSION_URL is correctly set to point at your Horizon.

View File

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

View File

@ -96,4 +96,5 @@ note. We can iterate on the content and application of the release note during
the review process. the review process.
For more information on how and when to create release notes, see the 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>`_.

View File

@ -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 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 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 migrate
adjutant runserver <port> 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**.

View File

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

View File

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

View File

@ -2,12 +2,9 @@
# of appearance. Changing the order has an impact on the overall integration # of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later. # 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

21
tox.ini
View File

@ -11,7 +11,9 @@ setenv = VIRTUAL_ENV={envdir}
[testenv:pep8] [testenv:pep8]
basepython = python3 basepython = python3
commands = flake8 commands =
flake8
doc8
[testenv:cover] [testenv:cover]
basepython = python3 basepython = python3
@ -32,16 +34,20 @@ commands = {posargs}
[testenv:docs] [testenv:docs]
basepython = python3 basepython = python3
deps = -r{toxinidir}/doc/requirements.txt
commands = 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] [testenv:api-ref]
basepython = python3 basepython = python3
deps = {[testenv:docs]deps}
commands = 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] [flake8]
ignore = D100,D101,D102,D103,D104,D105,D200,D203,D202,D204,D205,D208,D400,D401,W503 ignore = D100,D101,D102,D103,D104,D105,D200,D203,D202,D204,D205,D208,D400,D401,W503
@ -49,5 +55,6 @@ show-source = true
builtins = _ builtins = _
exclude=.venv,venv,.env,env,.git,.tox,dist,doc,*lib/python*,*egg,releasenotes,adjutant/api/migrations/*,adjutant/actions/migrations 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