From 92a0a825e5771a03c81069c5a19a6fc8adfbec15 Mon Sep 17 00:00:00 2001 From: zhurong Date: Thu, 19 Sep 2019 19:13:39 -0700 Subject: [PATCH] PDF documentation build Change-Id: I7db6a34ba582c048c40c450453f239ada6260ac2 --- .gitignore | 1 + doc/requirements.txt | 9 +++++ doc/source/conf.py | 47 ++++++++++------------- doc/source/index.rst | 14 +++---- panko/api/controllers/v2/utils.py | 50 +++++++++++++------------ panko/api/rbac.py | 4 +- panko/storage/hbase/utils.py | 9 ++++- panko/storage/sqlalchemy/alembic/env.py | 7 +++- requirements.txt | 3 ++ tox.ini | 12 ++++++ 10 files changed, 93 insertions(+), 63 deletions(-) create mode 100644 doc/requirements.txt diff --git a/.gitignore b/.gitignore index ec7d0af8..a26431e2 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ doc/source/api/ etc/panko/panko.conf subunit.log etc/panko/policy.yaml.sample +doc/source/_static/ diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 00000000..f77e364f --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,9 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. +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,!=2.1.0,>=1.6.2;python_version>='3.4' # BSD +openstackdocstheme>=1.20.0 # Apache-2.0 +sphinxcontrib-pecanwsme>=0.8.0 # Apache-2.0 +sphinxcontrib-httpdomain>=1.6.1 # BSD +reno>=2.7.0 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index 35c947bd..43155bb1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -11,22 +11,13 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import subprocess -import sys import os - -BASE_DIR = os.path.dirname(os.path.abspath(__file__)) -ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) -sys.path.insert(0, ROOT) -sys.path.insert(0, BASE_DIR) - -# This is required for ReadTheDocs.org, but isn't a bad idea anyway. -os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings' +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('../')) # -- General configuration ---------------------------------------------------- @@ -38,10 +29,8 @@ os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings' # or your custom ones. extensions = [ 'sphinx.ext.autodoc', - 'wsmeext.sphinxext', - 'sphinx.ext.coverage', - 'sphinx.ext.viewcode', 'sphinxcontrib.pecanwsme.rest', + 'sphinxcontrib.httpdomain', 'openstackdocstheme', 'oslo_policy.sphinxpolicygen' ] @@ -122,9 +111,9 @@ html_theme = 'openstackdocs' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -html_theme_options = { - "nosidebar": "false" -} +#html_theme_options = { +# "nosidebar": "false" +#} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -152,7 +141,7 @@ html_theme_options = { # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -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. @@ -198,21 +187,25 @@ htmlhelp_basename = 'Pankodoc' # -- 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': '', + 'makeindex': '', + 'printindex': '', + 'preamble': r'\setcounter{tocdepth}{3}', + 'maxlistdepth': '10', } +# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664 +latex_use_xindy = False + +# Disable smartquotes, they don't work in latex +smartquotes_excludes = {'builders': ['latex']} + +latex_domain_indices = False + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ - ('index', 'Panko.tex', u'Panko Documentation', + ('index', 'doc-panko.tex', u'Panko Documentation', u'OpenStack Foundation', 'manual'), ] diff --git a/doc/source/index.rst b/doc/source/index.rst index e287afca..1a3cdff7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,8 +36,6 @@ Overview contributor/index webapi/index -.. update index - Sample Configuration Files ========================== @@ -46,9 +44,11 @@ Sample Configuration Files configuration/sample_policy -Indices and tables -================== +.. only:: html -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + Indices and tables + ================== + + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/panko/api/controllers/v2/utils.py b/panko/api/controllers/v2/utils.py index b11c2787..c57dd0e3 100644 --- a/panko/api/controllers/v2/utils.py +++ b/panko/api/controllers/v2/utils.py @@ -77,36 +77,38 @@ def set_pagination_options(sort, limit, marker, api_model): Arguments: sort -- List of sorting criteria. Each sorting option has to format - : + : - Valid sort keys: message_id, generated - (SUPPORT_SORT_KEYS in panko/event/storage/models.py) - Valid sort directions: asc (ascending), desc (descending) - (SUPPORT_DIRS in panko/event/storage/models.py) - This defaults to asc if unspecified - (DEFAULT_DIR in panko/event/storage/models.py) + Valid sort keys: message_id, generated + (SUPPORT_SORT_KEYS in panko/event/storage/models.py) + Valid sort directions: asc (ascending), desc (descending) + (SUPPORT_DIRS in panko/event/storage/models.py) + This defaults to asc if unspecified + (DEFAULT_DIR in panko/event/storage/models.py) - impl_sqlalchemy.py: - (see _get_pagination_query) - If sort list is empty, this defaults to - ['generated:asc', 'message_id:asc'] - (DEFAULT_SORT in panko/event/storage/models.py) + impl_sqlalchemy.py: + (see _get_pagination_query) + If sort list is empty, this defaults to + ['generated:asc', 'message_id:asc'] + (DEFAULT_SORT in panko/event/storage/models.py) limit -- Integer specifying maximum number of values to return - If unspecified, this defaults to - pecan.request.cfg.api.default_api_return_limit - marker -- If specified, assumed to be an integer and assumed to be the - message id of the last object on the previous page of the results - api_model -- Specifies the class implementing the api model to use for - this pagination. The class is expected to provide the - following members: + If unspecified, this defaults to + pecan.request.cfg.api.default_api_return_limit - SUPPORT_DIRS - SUPPORT_SORT_KEYS - DEFAULT_DIR - DEFAULT_SORT - PRIMARY_KEY + marker -- If specified, assumed to be an integer and assumed to be the + message id of the last object on the previous page of the results + + api_model -- Specifies the class implementing the api model to use for + this pagination. The class is expected to provide the + following members: + + SUPPORT_DIRS + SUPPORT_SORT_KEYS + DEFAULT_DIR + DEFAULT_SORT + PRIMARY_KEY """ if limit and limit <= 0: raise wsme.exc.InvalidInput('limit', limit, diff --git a/panko/api/rbac.py b/panko/api/rbac.py index effbc4e1..9d92abd3 100644 --- a/panko/api/rbac.py +++ b/panko/api/rbac.py @@ -76,9 +76,9 @@ def get_limited_to(headers): :param headers: HTTP headers dictionary :return: A tuple of (user, project), set to None if there's no limit on - one of these. - + one of these. """ + init() policy_dict = dict() diff --git a/panko/storage/hbase/utils.py b/panko/storage/hbase/utils.py index d59e05e2..c5d51121 100644 --- a/panko/storage/hbase/utils.py +++ b/panko/storage/hbase/utils.py @@ -16,7 +16,12 @@ import copy import datetime import bson.json_util -from happybase.hbase import ttypes +try: + from happybase.hbase.ttypes import AlreadyExists +except ImportError: + # import happybase to enable Hbase_thrift module + import happybase # noqa + from Hbase_thrift import AlreadyExists from oslo_log import log from oslo_serialization import jsonutils import six @@ -232,7 +237,7 @@ def create_tables(conn, tables, column_families): for table in tables: try: conn.create_table(table, column_families) - except ttypes.AlreadyExists: + except AlreadyExists: if conn.table_prefix: table = ("%(table_prefix)s" "%(separator)s" diff --git a/panko/storage/sqlalchemy/alembic/env.py b/panko/storage/sqlalchemy/alembic/env.py index 2bdc942c..ae12b11c 100644 --- a/panko/storage/sqlalchemy/alembic/env.py +++ b/panko/storage/sqlalchemy/alembic/env.py @@ -12,13 +12,18 @@ # under the License. from __future__ import with_statement + +import os + +from alembic import config as alembic_config from alembic import context from sqlalchemy import engine_from_config, pool from logging.config import fileConfig # this is the Alembic Config object, which provides # access to the values within the .ini file in use. -config = context.config +config = alembic_config.Config(os.path.join(os.path.dirname(__file__), + 'alembic.ini')) # Interpret the config file for Python logging. # This line sets up loggers basically. diff --git a/requirements.txt b/requirements.txt index cae968ec..ea5f1c4e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -29,3 +29,6 @@ alembic>=0.7.6,!=0.8.1,!=0.9.0 # NOTE(jd) We do not import it directly, but WSME datetime string parsing # behaviour changes when this library is installed python-dateutil>=2.4.2 # BSD +happybase!=0.7,!=1.0.0;python_version=='2.7' # MIT +pymongo!=3.1 # Apache-2.0 +elasticsearch<3.0.0 # Apache-2.0 diff --git a/tox.ini b/tox.ini index 1c4e9d42..c7d663fa 100644 --- a/tox.ini +++ b/tox.ini @@ -54,9 +54,21 @@ commands = oslopolicy-sample-generator --config-file=etc/panko/panko-policy-gene [testenv:docs] basepython = python3 +deps = -r{toxinidir}/doc/requirements.txt commands = python setup.py build_sphinx setenv = PYTHONHASHSEED=0 +[testenv:pdf-docs] +basepython = python3 +deps = {[testenv:docs]deps} +whitelist_externals = + rm + make +commands = + rm -rf doc/build/pdf + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf + [testenv:venv] basepython = python3 commands = {posargs}