diff options
author | Gordon Chung <chungg@ca.ibm.com> | 2014-04-10 16:25:36 -0400 |
---|---|---|
committer | Gordon Chung <chungg@ca.ibm.com> | 2014-04-10 16:45:14 -0400 |
commit | 3e4f5939848e1da99c0291abfb1d83b45abc9aab (patch) | |
tree | b6df1c1f469ded1402eb09824dca9e1b96657003 | |
parent | ba58d010571594158aec27f6bbd5e4dcfe03ddd9 (diff) | |
download | pycadf-3e4f5939848e1da99c0291abfb1d83b45abc9aab.tar.gz |
reorder documentation
- reorder documentation so it's grouped logically.
- add api docstring modules
Change-Id: I47e49634fe7d8bb16a51f3045e7fe53683d56d1a
-rw-r--r-- | .gitignore | 2 | ||||
-rw-r--r-- | doc/ext/__init__.py | 0 | ||||
-rw-r--r-- | doc/ext/apidoc.py | 41 | ||||
-rw-r--r-- | doc/source/api/index.rst | 8 | ||||
-rw-r--r-- | doc/source/conf.py | 8 | ||||
-rw-r--r-- | doc/source/contributing.rst | 31 | ||||
-rw-r--r-- | doc/source/index.rst | 33 | ||||
-rw-r--r-- | setup.cfg | 6 |
8 files changed, 105 insertions, 24 deletions
@@ -9,7 +9,7 @@ ChangeLog *.egg-info/ build/ doc/build/ -doc/source/api/autoindex.rst +doc/source/api dist/ .testrepository/ .project diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/ext/__init__.py diff --git a/doc/ext/apidoc.py b/doc/ext/apidoc.py new file mode 100644 index 0000000..c23d55f --- /dev/null +++ b/doc/ext/apidoc.py @@ -0,0 +1,41 @@ +# Copyright 2013 OpenStack Foundation +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +import os.path as path + +from sphinx import apidoc + + +# NOTE(gordc): pbr will run Sphinx multiple times when it generates +# documentation. Once for each builder. To run this extension we use the +# 'builder-inited' hook that fires at the beginning of a Sphinx build. +# We use ``run_already`` to make sure apidocs are only generated once +# even if Sphinx is run multiple times. +run_already = False + + +def run_apidoc(app): + global run_already + if run_already: + return + run_already = True + + package_dir = path.abspath(path.join(app.srcdir, '..', '..', 'pycadf')) + source_dir = path.join(app.srcdir, 'api') + apidoc.main(['apidoc', package_dir, '-f', + '-H', 'pyCADF Modules', + '-o', source_dir]) + + +def setup(app): + app.connect('builder-inited', run_apidoc) diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst deleted file mode 100644 index 3da71d0..0000000 --- a/doc/source/api/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -============== - API Reference -============== - -.. toctree:: - :maxdepth: 1 - - autoindex diff --git a/doc/source/conf.py b/doc/source/conf.py index 6378da7..1369c50 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -13,6 +13,9 @@ import sys, os +# NOTE(gordc): path for Sphinx ext.apidoc +sys.path.insert(0, os.path.abspath('..')) + # This is required for ReadTheDocs.org, but isn't a bad idea anyway. os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings' @@ -35,7 +38,8 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.viewcode', - 'oslosphinx' + 'oslosphinx', + 'ext.apidoc' ] # Add any paths that contain templates here, relative to this directory. @@ -136,7 +140,7 @@ html_theme_options = { # 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'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..bcb0aff --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,31 @@ +.. + Copyright 2014 IBM Corp. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +.. _contributing: + +============= + Contributing +============= + +Contributions to the pyCADF library is welcomed. + +Important links: + +1. `Github repository`_ + +2. `Launchpad project`_ + +.. _Github repository: https://github.com/openstack/pycadf +.. _Launchpad project: https://launchpad.net/pycadf diff --git a/doc/source/index.rst b/doc/source/index.rst index a72e1a9..37c2d9d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -35,18 +35,30 @@ contribute to the project. .. _CADF (Cloud Audit Data Federation Working Group): http://www.dmtf.org/standards/cadf -Table of contents -================= +Getting Started +=============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - api/index - specification/index - event_concept - middleware + event_concept + middleware -.. update index +Developer Documentation +======================= + +.. toctree:: + :maxdepth: 1 + + contributing + specification/index + +Code Documentation +================== +.. toctree:: + :maxdepth: 1 + + api/modules Indices and tables ================== @@ -54,8 +66,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - -To Do -===== - -.. todolist:: @@ -35,3 +35,9 @@ all_files = 1 [upload_sphinx] upload-dir = doc/build/html + +[pbr] +warnerrors = True +#autodoc_tree_index_modules = True +#autodoc_tree_root = ./pycadf + |