From f81cf9a905f00e476851cbe8d81c5f81ac47a165 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Sun, 11 Aug 2019 09:59:19 +0200 Subject: [PATCH] Update docs building Follow PTI [1] for doc building: * Create doc/requirements.txt file with all docs requirements. * Switch to openstackdocstheme and update conf.py for this. * Move doc8 to pep8 section since it's a linter. Additionally: * Fix all build errors with doc building. * Update requirements list with license info. * Use hacking instead of flake directly. * Remove unused _static files, those are not needed. * Update git URLs, fix contributor guide URL * Move README.md to RST, everything else in this repo is RST * Publish documents to docs.o.o - note that https://adjutant.readthedocs.io/en/latest/ was last updated in March 2018 This adds jobs for building of release notes - only building since there's no content yet - and publishing of documentation. Publishing of api-ref can be done via: https://review.opendev.org/675766 [1] https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation Change-Id: I82f56ef5ea800899b2a8db795b6cf2b21d03ac7a --- .zuul.yaml | 2 ++ README.md | 15 ----------- README.rst | 40 +++++++++++++++++++++++++++++ api-ref/source/_static/fonts/.keep | 0 api-ref/source/conf.py | 19 +++++++------- api-ref/source/index.rst | 8 ++---- api-ref/source/parameters.yaml | 24 ++++++++--------- api-ref/source/taskviews.inc | 4 +-- api-ref/source/v1-api-reference.rst | 13 +++++----- doc/requirements.txt | 5 ++++ doc/source/_static/fonts/.keep | 0 doc/source/conf.py | 31 ++++++++-------------- doc/source/devstack-guide.rst | 6 ++--- doc/source/index.rst | 24 ++++++++--------- doc/source/release-notes.rst | 3 ++- package_readme.rst | 21 ++++++++++++--- releasenotes/source/conf.py | 24 +++++------------ releasenotes/source/index.rst | 2 +- releasenotes/source/unreleased.rst | 2 +- setup.cfg | 9 +------ test-requirements.txt | 15 +++++------ tox.ini | 21 ++++++++++----- 22 files changed, 151 insertions(+), 137 deletions(-) delete mode 100644 README.md create mode 100644 README.rst delete mode 100644 api-ref/source/_static/fonts/.keep create mode 100644 doc/requirements.txt delete mode 100644 doc/source/_static/fonts/.keep diff --git a/.zuul.yaml b/.zuul.yaml index 31f71db..6f9bd25 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-python36-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 238fe5a..237f076 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 = @@ -33,13 +33,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