Merge "Produce API documentation"

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 -

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']

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

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

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