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

.gitignore

@@ -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

doc/README.rst

@@ -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
+=================
 
-Manually
-========
+#. Generate the code.rst file so that Sphinx will pull in our docstrings::
 
-  1. Generate the code.rst file so that Sphinx will pull in our docstrings::
+    $ python doc/generate_autodoc_index.py
 
-      % ./generate_autodoc_index.py
+#. Run `sphinx_build` to produce the docs in HTML::
 
-  2. Run `sphinx_build`::
+    $ sphinx-build -b html doc/source/ build/sphinx/html/
 
-      % sphinx-build -b html source build/html
+#. Similarly, build the man pages (optional)::
 
+    $ sphinx-build -b man doc/source/ build/sphinx/man/
 
-The docs have been built
-========================
-
-Check out the `build` directory to find them. Yay!
+After building
+==============
 
+Navigate to the `build/sphinx/html` directory to browse generated the HTML docs.

doc/generate_autodoc_index.py

@@ -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"""