diff --git a/bindep.txt b/bindep.txt index 03d6ccb95..84892a123 100644 --- a/bindep.txt +++ b/bindep.txt @@ -15,3 +15,7 @@ pki-kra [platform:rpm] #Required for cryptography lib libssl-dev [platform:dpkg] openssl-devel [platform:rpm] + +# libsrvg2 is needed for sphinxcontrib-svg2pdfconverter in docs builds. +librsvg2-tools [doc platform:rpm] +librsvg2-bin [doc platform:dpkg] diff --git a/doc/requirements.txt b/doc/requirements.txt index 487d27ace..9ca111a80 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,7 +1,8 @@ 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 +sphinx>=1.8.0,!=2.1.0;python_version>='3.4' # BSD sphinxcontrib-httpdomain>=1.3.0 # BSD sphinxcontrib-blockdiag>=1.5.4 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD reno>=2.5.0 # Apache-2.0 os-api-ref>=1.4.0 # Apache-2.0 openstackdocstheme>=1.18.1 # Apache-2.0 diff --git a/doc/source/conf.py b/doc/source/conf.py index 4034bb57c..5b710095a 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -27,6 +27,7 @@ extensions = [ 'oslo_config.sphinxconfiggen', 'oslo_policy.sphinxext', 'oslo_policy.sphinxpolicygen', + 'sphinxcontrib.rsvgconverter', ] config_generator_config_file = [ @@ -89,10 +90,12 @@ htmlhelp_basename = '%sdoc' % project # [howto/manual]). latex_documents = [ ('index', - '%s.tex' % project, + 'doc-barbican.tex', u'%s Documentation' % project, u'OpenStack Foundation', 'manual'), ] +latex_use_xindy = False + # Example configuration for intersphinx: refer to the Python standard library. # intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/contributor/architecture.rst b/doc/source/contributor/architecture.rst index 56f953d8e..5cc47d389 100644 --- a/doc/source/contributor/architecture.rst +++ b/doc/source/contributor/architecture.rst @@ -12,7 +12,7 @@ Overall Architecture The next figure presents an overall logical diagram for Barbican. -.. image:: ./../images/barbican-overall-architecture.gif +.. image:: ./../images/barbican-overall-architecture.png The API node(s) handle incoming REST requests to Barbican. These nodes can interact with the database directly if the request can be completed @@ -35,7 +35,7 @@ logging. The next figure examines the components within Barbican. -.. image:: ./../images/barbican-components.gif +.. image:: ./../images/barbican-components.png Several potential clients of the Barbican REST interface are noted, including `Castellan `_ which presents a generic diff --git a/doc/source/images/barbican-components.gif b/doc/source/images/barbican-components.gif deleted file mode 100644 index 0fd0a2006..000000000 Binary files a/doc/source/images/barbican-components.gif and /dev/null differ diff --git a/doc/source/images/barbican-components.png b/doc/source/images/barbican-components.png new file mode 100644 index 000000000..a1e301e59 Binary files /dev/null and b/doc/source/images/barbican-components.png differ diff --git a/doc/source/images/barbican-overall-architecture.gif b/doc/source/images/barbican-overall-architecture.gif deleted file mode 100644 index e963c10c8..000000000 Binary files a/doc/source/images/barbican-overall-architecture.gif and /dev/null differ diff --git a/doc/source/images/barbican-overall-architecture.png b/doc/source/images/barbican-overall-architecture.png new file mode 100644 index 000000000..0f9b69c3a Binary files /dev/null and b/doc/source/images/barbican-overall-architecture.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst index e8c8eee9e..a1935c468 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -23,7 +23,7 @@ API. configuration/index contributor/index .. toctree:: - :maxdepth: 1 + :maxdepth: 2 api/index.rst @@ -31,7 +31,7 @@ Sample Files ============ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 sample_config sample_policy diff --git a/lower-constraints.txt b/lower-constraints.txt index 5100b2429..a71a47178 100644 --- a/lower-constraints.txt +++ b/lower-constraints.txt @@ -114,6 +114,7 @@ six==1.10.0 smmap2==2.0.3 snowballstemmer==1.2.1 Sphinx==1.6.2 +sphinxcontrib-svg2pdfconverter==0.1.0 sphinxcontrib-websupport==1.0.1 sqlalchemy-migrate==0.11.0 SQLAlchemy==1.0.10 diff --git a/tox.ini b/tox.ini index bf77573b1..c41765e74 100644 --- a/tox.ini +++ b/tox.ini @@ -83,10 +83,19 @@ description = Build main documentation basepython = python3 deps = -r{toxinidir}/doc/requirements.txt commands= - rm -rf doc/build + rm -rf doc/build doc/build/doctrees sphinx-build -W -b html doc/source doc/build/html whitelist_externals = rm +[testenv:pdf-docs] +basepython = python3 +deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf + [testenv:api-guide] basepython = python3 # This environment is called from CI scripts to test and publish @@ -174,4 +183,3 @@ deps = -c{toxinidir}/lower-constraints.txt -r{toxinidir}/test-requirements.txt -r{toxinidir}/requirements.txt -