Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
updating keystone developer documentation
updating docstrings to remove errors in automodule generation updating setup.py to generate source documentation blueprint keystone-documentation bug 843056 Change-Id: Ie8dfedc89c1a6d9ffa5106d29dd19837b02746ce
- Loading branch information
Showing
20 changed files
with
935 additions
and
100 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
========================== | ||
Building the Documentation | ||
========================== | ||
|
||
Using setup.py | ||
============== | ||
|
||
From the project root, just type:: | ||
|
||
% setup.py build_sphinx | ||
|
||
|
||
|
||
Manually | ||
======== | ||
|
||
1. Generate the code.rst file so that Sphinx will pull in our docstrings:: | ||
|
||
% ./generate_autodoc_index.py | ||
|
||
2. Run `sphinx_build`:: | ||
|
||
% sphinx-build -b html source build/html | ||
|
||
|
||
The docs have been built | ||
======================== | ||
|
||
Check out the `build` directory to find them. Yay! | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
#!/usr/bin/env python | ||
"""Generates files for sphinx documentation using a simple Autodoc based | ||
template. | ||
To use: | ||
cd keystone/doc | ||
./generate_autodoc_index.py | ||
""" | ||
|
||
import os | ||
|
||
RSTDIR="source/sourcecode" | ||
SOURCE="../keystone" | ||
|
||
def find_autodoc_modules(): | ||
"""returns a list of modules in the SOURCE directory""" | ||
modlist = [] | ||
for root, dirs, files in os.walk(SOURCE): | ||
for filename in files: | ||
if filename.endswith(".py"): | ||
# root = ../keystone/test/unit | ||
# filename = base.py | ||
# remove the first two pieces of the root | ||
elements = root.split(os.path.sep)[1:] | ||
# and get the base module name | ||
base, extension = os.path.splitext(filename) | ||
if not (base == "__init__"): | ||
elements.append(base) | ||
modlist.append(".".join(elements)) | ||
return modlist | ||
|
||
if not(os.path.exists(RSTDIR)): | ||
os.mkdir(RSTDIR) | ||
|
||
INDEXOUT = open("%s/autoindex.rst" % RSTDIR, "w") | ||
INDEXOUT.write("Source Code Index\n") | ||
INDEXOUT.write("=================\n") | ||
INDEXOUT.write(".. toctree::\n") | ||
INDEXOUT.write(" :maxdepth: 1\n") | ||
INDEXOUT.write("\n") | ||
|
||
for module in find_autodoc_modules(): | ||
generated_file = "%s/%s.rst" % (RSTDIR, module) | ||
print "Generating %s" % generated_file | ||
|
||
INDEXOUT.write(" %s\n" % module) | ||
FILEOUT = open(generated_file, "w") | ||
FILEOUT.write("The :mod:`%s` Module\n" % module) | ||
FILEOUT.write("==============================" | ||
"==============================" | ||
"==============================\n") | ||
FILEOUT.write(".. automodule:: %s\n" % module) | ||
FILEOUT.write(" :members:\n") | ||
FILEOUT.write(" :undoc-members:\n") | ||
FILEOUT.write(" :show-inheritance:\n") | ||
FILEOUT.close() | ||
|
||
INDEXOUT.close() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -63,4 +63,4 @@ Curl examples | |
:maxdepth: 1 | ||
|
||
adminAPI_curl_examples | ||
serviceAPI_curl_examples | ||
serviceAPI_curl_examples |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.