Browse Source

Replace pbr autodoc with sphinxcontrib-apidoc

This fixes local building of the documentation using tox, and allows the
gate to stop relying on pbr and move completely to the new docs PTI.

http://lists.openstack.org/pipermail/openstack-dev/2018-March/128594.html

Change-Id: I485acda07098a435753e91c1ca45e586de199c35
tags/3.16.0
Stephen Finucane 1 year ago
parent
commit
63d741fd66
4 changed files with 16 additions and 27 deletions
  1. 2
    1
      doc/requirements.txt
  2. 11
    8
      doc/source/conf.py
  3. 0
    16
      setup.cfg
  4. 3
    2
      tox.ini

+ 2
- 1
doc/requirements.txt View File

@@ -3,4 +3,5 @@
3 3
 # process, which may cause wedges in the gate later.
4 4
 openstackdocstheme>=1.18.1 # Apache-2.0
5 5
 reno>=2.5.0 # Apache-2.0
6
-sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
6
+sphinx!=1.6.6,!=1.6.7,>=1.6.5 # BSD
7
+sphinxcontrib-apidoc>=0.2.0 # BSD

+ 11
- 8
doc/source/conf.py View File

@@ -12,16 +12,8 @@
12 12
 # All configuration values have a default; values that are commented out
13 13
 # serve to show the default.
14 14
 
15
-import os
16
-import sys
17
-
18 15
 import pbr.version
19 16
 
20
-# If extensions (or modules to document with autodoc) are in another directory,
21
-# add these directories to sys.path here. If the directory is relative to the
22
-# documentation root, use os.path.abspath to make it absolute, like shown here.
23
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
24
-
25 17
 # -- General configuration ----------------------------------------------------
26 18
 
27 19
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -35,6 +27,7 @@ extensions = ['sphinx.ext.autodoc',
35 27
               'openstackdocstheme',
36 28
               'stevedore.sphinxext',
37 29
               'cliff.sphinxext',
30
+              'sphinxcontrib.apidoc',
38 31
               ]
39 32
 
40 33
 # openstackdocstheme options
@@ -282,3 +275,13 @@ autoprogram_cliff_application = 'openstack'
282 275
 autoprogram_cliff_ignored = [
283 276
     '--help', '--format', '--column', '--max-width', '--fit-width',
284 277
     '--print-empty', '--prefix', '--noindent', '--quote']
278
+
279
+
280
+# -- Options for sphinxcontrib.apidoc ----------------------------------------
281
+
282
+apidoc_module_dir = '../../openstackclient'
283
+apidoc_excluded_paths = [
284
+    'volume/v3',
285
+    'tests',
286
+]
287
+apidoc_output_dir = 'contributor/api'

+ 0
- 16
setup.cfg View File

@@ -714,22 +714,6 @@ openstack.volume.v3 =
714 714
     volume_transfer_request_list = openstackclient.volume.v2.volume_transfer_request:ListTransferRequest
715 715
     volume_transfer_request_show = openstackclient.volume.v2.volume_transfer_request:ShowTransferRequest
716 716
 
717
-[pbr]
718
-autodoc_tree_index_modules = True
719
-autodoc_tree_excludes =
720
-    setup.py
721
-    openstackclient/volume/v3
722
-    openstackclient/tests/
723
-    openstackclient/tests/*
724
-api_doc_dir = contributor/api
725
-
726
-[build_sphinx]
727
-builders = html,man
728
-all-files = 1
729
-warning-is-error = 1
730
-source-dir = doc/source
731
-build-dir = doc/build
732
-
733 717
 [upload_sphinx]
734 718
 upload-dir = doc/build/html
735 719
 

+ 3
- 2
tox.ini View File

@@ -113,12 +113,13 @@ deps =
113 113
   -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
114 114
   -r{toxinidir}/requirements.txt
115 115
   -r{toxinidir}/doc/requirements.txt
116
-commands = python setup.py build_sphinx
116
+commands =
117
+  sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html
118
+  sphinx-build -a -E -W -d doc/build/doctrees -b man doc/source doc/build/man
117 119
 
118 120
 [testenv:releasenotes]
119 121
 deps =
120 122
   -c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt}
121
-  -r{toxinidir}/requirements.txt
122 123
   -r{toxinidir}/doc/requirements.txt
123 124
 commands =
124 125
   sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html

Loading…
Cancel
Save