From 78c0766bec6640aa71d6a51f34538d921290496a Mon Sep 17 00:00:00 2001
From: Ian Wienand <iwienand@redhat.com>
Date: Thu, 25 May 2017 14:13:31 +1000
Subject: [PATCH] Produce API documentation

There's an increasing amount of pydoc based documentation.  Output the
module reference and link it into the developers main page.

One fixup to the rst needed

Change-Id: I1d43a1fe1c735eb4559e3d2b40834d1c8115c586
---
 diskimage_builder/block_device/level1/mbr.py | 21 ++++++++++++++------
 doc/source/conf.py                           |  2 +-
 doc/source/developer/index.rst               |  7 +++++++
 doc/source/index.rst                         |  6 ++++++
 setup.cfg                                    |  9 +++++++++
 5 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/diskimage_builder/block_device/level1/mbr.py b/diskimage_builder/block_device/level1/mbr.py
index 69cff736d..9e24455de 100644
--- a/diskimage_builder/block_device/level1/mbr.py
+++ b/diskimage_builder/block_device/level1/mbr.py
@@ -69,6 +69,7 @@ class MBR(object):
 
     Primary partitions are created first - and must also be passed in
     first.
+
     The extended partition layout is done in the way, that there is
     one entry in the MBR (the last) that uses the whole disk.
     EBR (extended boot records) are used to describe the partitions
@@ -76,21 +77,29 @@ class MBR(object):
     be used for all partitions and arbitrarily many partitions can be
     created in the same way (the EBR is placed as block 0 in each
     partition itself).
+
     In conjunction with a fixed and 'fits all' partition alignment the
     major design focus is maximum performance for the installed image
     (vs. minimal size).
+
     Because of the chosen default alignment of 1MiB there will be
     (1MiB - 512B) unused disk space for the MBR and also the same
     size unused in every partition.
+
     Assuming that 512 byte blocks are used, the resulting layout for
     extended partitions looks like (blocks offset in extended
     partition given):
-           0: MBR - 2047 blocks unused
-        2048: EBR for partition 1 - 2047 blocks unused
-        4096: Start of data for partition 1
-         ...
-           X: EBR for partition N - 2047 blocks unused
-      X+2048: Start of data for partition N
+
+    ======== ==============================================
+    Offset    Description
+    ======== ==============================================
+        0     MBR - 2047 blocks unused
+     2048     EBR for partition 1 - 2047 blocks unused
+     4096     Start of data for partition 1
+     ...     ...
+      X       EBR for partition N - 2047 blocks unused
+      X+2048  Start of data for partition N
+    ======== ==============================================
 
     Direct (native) writing of MBR, EBR (partition table) is
     implemented - no other parititoning library or tools is used -
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 793ab852e..9cb193f76 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -5,7 +5,7 @@ import os
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 sys.path.append(os.path.abspath('../lib'))
-extensions = ['oslosphinx', 'element_deps']
+extensions = ['oslosphinx', 'element_deps', 'sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/doc/source/developer/index.rst b/doc/source/developer/index.rst
index cc063806b..293df9196 100644
--- a/doc/source/developer/index.rst
+++ b/doc/source/developer/index.rst
@@ -35,6 +35,13 @@ and testing your changes.  When you are done editing, use ``git
 review`` to submit changes to the upstream gerrit.
 
 
+Python module documentation
+---------------------------
+
+For internal documentation on the DIB python components, see the
+:ref:`modindex`
+
+
 Finding Work
 ------------
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c683ab654..5f50bc851 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -56,3 +56,9 @@ Table of Contents
    developer/index
    elements
    specs/README
+
+.. # just link this on the dev page
+.. toctree::
+   :hidden:
+
+   api/autoindex
diff --git a/setup.cfg b/setup.cfg
index c5e5485e8..b48bb47de 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -21,6 +21,15 @@ build-dir = doc/build
 source-dir = doc/source
 warning-is-error = 1
 
+[pbr]
+autodoc_index_modules = 1
+autodoc_exclude_modules =
+     setup.py
+     diskimage_builder.tests.*
+     diskimage_builder.block_device.tests.*
+     # elements are a weird mix of scripts & python
+     diskimage_builder.elements.*
+
 [files]
 packages =
     diskimage_builder