From 276b1e4ed51af02af2c31cf4bfc0334285c23899 Mon Sep 17 00:00:00 2001 From: JUN JIE NAN Date: Mon, 23 Dec 2013 11:16:17 +0800 Subject: [PATCH] Added API reference document The API reference document is missing so addded it and enabled pep8 check for conf.py. Change-Id: I04236c5427d7ac624781fbfc920a79f855d8cd75 --- doc/.gitignore | 1 + doc/source/conf.py | 12 ++++++++ doc/source/ext/gen_ref.py | 58 +++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 9 ++++++ tox.ini | 2 +- 5 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 doc/source/ext/gen_ref.py diff --git a/doc/.gitignore b/doc/.gitignore index 567609b1..8e0be80f 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1 +1,2 @@ build/ +source/ref/ diff --git a/doc/source/conf.py b/doc/source/conf.py index 62a67256..aafb0c1b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,4 +1,15 @@ # -*- coding: utf-8 -*- +# 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. # # python-heatclient documentation build configuration file, created by # sphinx-quickstart on Sun Dec 6 14:19:25 2009. @@ -19,6 +30,7 @@ import os # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.append(os.path.abspath('.')) +execfile(os.path.join("ext", "gen_ref.py")) # -- General configuration ---------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be diff --git a/doc/source/ext/gen_ref.py b/doc/source/ext/gen_ref.py new file mode 100644 index 00000000..97b9bfde --- /dev/null +++ b/doc/source/ext/gen_ref.py @@ -0,0 +1,58 @@ +# -*- coding: utf-8 -*- +# 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 +import sys + +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) + + +def gen_ref(ver, title, names): + refdir = os.path.join(BASE_DIR, "ref") + pkg = "heatclient" + if ver: + pkg = "%s.%s" % (pkg, ver) + refdir = os.path.join(refdir, ver) + if not os.path.exists(refdir): + os.makedirs(refdir) + idxpath = os.path.join(refdir, "index.rst") + with open(idxpath, "w") as idx: + idx.write(("%(title)s\n" + "%(signs)s\n" + "\n" + ".. toctree::\n" + " :maxdepth: 1\n" + "\n") % {"title": title, "signs": "=" * len(title)}) + for name in names: + idx.write(" %s\n" % name) + rstpath = os.path.join(refdir, "%s.rst" % name) + with open(rstpath, "w") as rst: + rst.write(("%(title)s\n" + "%(signs)s\n" + "\n" + ".. automodule:: %(pkg)s.%(name)s\n" + " :members:\n" + " :undoc-members:\n" + " :show-inheritance:\n" + " :noindex:\n") + % {"title": name.capitalize(), + "signs": "=" * len(name), + "pkg": pkg, "name": name}) + +gen_ref("", "Client Reference", ["client", "exc"]) +gen_ref("v1", "Version 1 API Reference", + ["stacks", "resources", "events", "actions"]) diff --git a/doc/source/index.rst b/doc/source/index.rst index aeb15ec3..02fa7af3 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -20,6 +20,15 @@ Once you have done so, you can use the API like so:: >>> from heatclient.client import Client >>> heat = Client('1', endpoint=heat_url, token=auth_token) +Reference +--------- + +.. toctree:: + :maxdepth: 1 + + ref/index + ref/v1/index + Command-line Tool ================= diff --git a/tox.ini b/tox.ini index f77bad83..492d901a 100644 --- a/tox.ini +++ b/tox.ini @@ -28,4 +28,4 @@ downloadcache = ~/cache/pip show-source = True ignore = H233,H302 builtins = _ -exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build +exclude=.venv,.git,.tox,dist,*openstack/common*,*lib/python*,*egg,build