diff --git a/.zuul.yaml b/.zuul.yaml index 77d8060..5cb42a1 100644 --- a/.zuul.yaml +++ b/.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 diff --git a/README.md b/README.md deleted file mode 100644 index 434c5e0..0000000 --- a/README.md +++ /dev/null @@ -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'. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..dea24ab --- /dev/null +++ b/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`. diff --git a/api-ref/source/_static/fonts/.keep b/api-ref/source/_static/fonts/.keep deleted file mode 100644 index e69de29..0000000 diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py index a6c8e28..e250f78 100644 --- a/api-ref/source/conf.py +++ b/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 diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 4f3669b..cb2fc6c 100644 --- a/api-ref/source/index.rst +++ b/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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index cf80987..34dff5e 100644 --- a/api-ref/source/parameters.yaml +++ b/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. diff --git a/api-ref/source/taskviews.inc b/api-ref/source/taskviews.inc index e6d0355..6e92083 100644 --- a/api-ref/source/taskviews.inc +++ b/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 diff --git a/api-ref/source/v1-api-reference.rst b/api-ref/source/v1-api-reference.rst index 2eea57f..403e9fe 100644 --- a/api-ref/source/v1-api-reference.rst +++ b/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. diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..19dd2e5 --- /dev/null +++ b/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 diff --git a/doc/source/_static/fonts/.keep b/doc/source/_static/fonts/.keep deleted file mode 100644 index e69de29..0000000 diff --git a/doc/source/conf.py b/doc/source/conf.py index 91f91b7..d457cf0 100644 --- a/doc/source/conf.py +++ b/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]). diff --git a/doc/source/devstack-guide.rst b/doc/source/devstack-guide.rst index af866cf..c8a0f03 100644 --- a/doc/source/devstack-guide.rst +++ b/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 `_ +be found `here `_. 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index acba109..e55beb4 100644 --- a/doc/source/index.rst +++ b/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 + + 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 `_ -* `adjutant-ui `_ +* `python-adjutantclient `_ +* `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. `_ Changes should be submitted through the OpenStack gerrit, the guide for contributing to OpenStack projects is -`here `_ . +`here `_ . diff --git a/doc/source/release-notes.rst b/doc/source/release-notes.rst index 6f47b34..3bc4b59 100644 --- a/doc/source/release-notes.rst +++ b/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 `_. \ No newline at end of file +`project-team-guide +`_. diff --git a/package_readme.rst b/package_readme.rst index 3e0cec3..6a4da05 100644 --- a/package_readme.rst +++ b/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 -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**. \ No newline at end of file +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**. diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index 483a6d5..dd6e055 100644 --- a/releasenotes/source/conf.py +++ b/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' \ No newline at end of file diff --git a/releasenotes/source/index.rst b/releasenotes/source/index.rst index b717294..c8847a9 100644 --- a/releasenotes/source/index.rst +++ b/releasenotes/source/index.rst @@ -18,4 +18,4 @@ Adjutant Release Notes .. toctree:: :maxdepth: 1 - unreleased \ No newline at end of file + unreleased diff --git a/releasenotes/source/unreleased.rst b/releasenotes/source/unreleased.rst index 6f1e544..99cbac5 100644 --- a/releasenotes/source/unreleased.rst +++ b/releasenotes/source/unreleased.rst @@ -2,4 +2,4 @@ Current Series Release Notes ============================ - .. release-notes:: \ No newline at end of file + .. release-notes:: diff --git a/setup.cfg b/setup.cfg index 663911c..d34a9d0 100644 --- a/setup.cfg +++ b/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 diff --git a/test-requirements.txt b/test-requirements.txt index 8d6e93c..e5f3efe 100644 --- a/test-requirements.txt +++ b/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 -doc8>=0.8.0 -flake8>=3.7.7 -mock>=3.0.5 -os-api-ref>=1.6.1 # Apache-2.0 -sphinx-rtd-theme>=0.4.3 -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 \ No newline at end of file +flake8>=3.7.7 # MIT + +coverage>=4.5.3 # Apache-2.0 +doc8>=0.8.0 # Apache-2.0 +mock>=3.0.0 # BSD +Pygments>=2.2.0 # BSD license diff --git a/tox.ini b/tox.ini index f1a34bb..4dca6dd 100644 --- a/tox.ini +++ b/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 - python setup.py build_sphinx + sphinx-build -W -b html -d doc/build/doctrees doc/source doc/build/html [testenv:api-ref] basepython = python3 +deps = {[testenv:docs]deps} commands = - doc8 api-ref/source - python setup.py build_sphinx -s api-ref/source/ --build-dir api-ref/build/ + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html +[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] -commands = sphinx-build -a -E -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html \ No newline at end of file +[doc8] +ignore-path=.tox,*.egg-info,doc/build,.eggs/*/EGG-INFO/*.txt,./*.txt,adjutant +extension=.txt,.rst,.inc