Revised documentation build process (bug #843056)
- Manual method now produces docs in the same location as setup.py - Added manual command to build man pages - Manual method is now executable from the project root - To conform with similar commands - Generated sourcecode rst's are now ignored by git - Removed unused gitignore entries related to docs Change-Id: I86fb38cdee957f5ba6717e1438494c7a148f4855
This commit is contained in:
parent
c18c093573
commit
cf803ba266
|
@ -13,9 +13,8 @@ keystone.token.db
|
|||
*.pid
|
||||
pidfile
|
||||
*.komodoproject
|
||||
doc/build/
|
||||
build/
|
||||
doc/guide/target
|
||||
doc/source/sourcecode
|
||||
.keystone-venv/
|
||||
keystone.egg-info/
|
||||
run_tests.err.log
|
||||
|
|
|
@ -2,29 +2,29 @@
|
|||
Building the Documentation
|
||||
==========================
|
||||
|
||||
Using setup.py
|
||||
==============
|
||||
Building automatically
|
||||
======================
|
||||
|
||||
From the project root, just type::
|
||||
|
||||
% setup.py build_sphinx
|
||||
$ python setup.py build_sphinx
|
||||
|
||||
Building manually
|
||||
=================
|
||||
|
||||
#. Generate the code.rst file so that Sphinx will pull in our docstrings::
|
||||
|
||||
Manually
|
||||
========
|
||||
$ python doc/generate_autodoc_index.py
|
||||
|
||||
1. Generate the code.rst file so that Sphinx will pull in our docstrings::
|
||||
#. Run `sphinx_build` to produce the docs in HTML::
|
||||
|
||||
% ./generate_autodoc_index.py
|
||||
$ sphinx-build -b html doc/source/ build/sphinx/html/
|
||||
|
||||
2. Run `sphinx_build`::
|
||||
#. Similarly, build the man pages (optional)::
|
||||
|
||||
% sphinx-build -b html source build/html
|
||||
$ sphinx-build -b man doc/source/ build/sphinx/man/
|
||||
|
||||
After building
|
||||
==============
|
||||
|
||||
The docs have been built
|
||||
========================
|
||||
|
||||
Check out the `build` directory to find them. Yay!
|
||||
|
||||
Navigate to the `build/sphinx/html` directory to browse generated the HTML docs.
|
||||
|
|
|
@ -1,15 +1,18 @@
|
|||
#!/usr/bin/env python
|
||||
"""Generates files for sphinx documentation using a simple Autodoc based
|
||||
template.
|
||||
To use:
|
||||
cd keystone/doc
|
||||
./generate_autodoc_index.py
|
||||
|
||||
To use, just run as a script:
|
||||
$ python doc/generate_autodoc_index.py
|
||||
"""
|
||||
|
||||
import os
|
||||
|
||||
RSTDIR="source/sourcecode"
|
||||
SOURCE="../keystone"
|
||||
|
||||
base_dir = os.path.dirname(os.path.abspath(__file__))
|
||||
RSTDIR=os.path.join(base_dir, "source", "sourcecode")
|
||||
SOURCE=os.path.join(base_dir, "..", "keystone")
|
||||
|
||||
|
||||
def find_autodoc_modules():
|
||||
"""returns a list of modules in the SOURCE directory"""
|
||||
|
|
Loading…
Reference in New Issue