Modify sphinx documentation configuration

Akrog · Akrog · commit da4bca84be22 · 2015-11-29T18:53:54.000+01:00
This patch makes some changes to sphinx configuration:

- Generate apidoc in docs/api
- Generate individual files for API
- Add inherited members in documentation
- Include __init__ methods in the documenattion
- Groupd members by type instead of alphabetically
- Exclude base.py and common.py from API documentation
- Move API documentation to TOC and out of Indices and tables
diff --git a/Makefile b/Makefile
@@ -67,9 +67,9 @@ coverage-html:
 	$(BROWSER) htmlcov/index.html
 
 docs:
-	rm -f docs/gcs_client.rst
-	rm -f docs/modules.rst
-	sphinx-apidoc -o docs/ gcs_client
+	rm -f docs/api/*.rst
+	# Create individual files, and exclude common and base modules.
+	sphinx-apidoc -e -M -o docs/api gcs_client gcs_client/base.py gcs_client/common.py
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html
diff --git a/docs/api/gcs_client.bucket.rst b/docs/api/gcs_client.bucket.rst
@@ -0,0 +1,7 @@
+gcs_client.bucket module
+========================
+
+.. automodule:: gcs_client.bucket
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.constants.acl.rst b/docs/api/gcs_client.constants.acl.rst
@@ -0,0 +1,7 @@
+gcs_client.constants.acl module
+===============================
+
+.. automodule:: gcs_client.constants.acl
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.constants.projection.rst b/docs/api/gcs_client.constants.projection.rst
@@ -0,0 +1,7 @@
+gcs_client.constants.projection module
+======================================
+
+.. automodule:: gcs_client.constants.projection
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.constants.rst b/docs/api/gcs_client.constants.rst
@@ -0,0 +1,18 @@
+gcs_client.constants package
+============================
+
+.. automodule:: gcs_client.constants
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   gcs_client.constants.acl
+   gcs_client.constants.projection
+   gcs_client.constants.scope
+   gcs_client.constants.storage_class
+
diff --git a/docs/api/gcs_client.constants.scope.rst b/docs/api/gcs_client.constants.scope.rst
@@ -0,0 +1,7 @@
+gcs_client.constants.scope module
+=================================
+
+.. automodule:: gcs_client.constants.scope
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.constants.storage_class.rst b/docs/api/gcs_client.constants.storage_class.rst
@@ -0,0 +1,7 @@
+gcs_client.constants.storage_class module
+=========================================
+
+.. automodule:: gcs_client.constants.storage_class
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.credentials.rst b/docs/api/gcs_client.credentials.rst
@@ -0,0 +1,7 @@
+gcs_client.credentials module
+=============================
+
+.. automodule:: gcs_client.credentials
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.errors.rst b/docs/api/gcs_client.errors.rst
@@ -0,0 +1,7 @@
+gcs_client.errors module
+========================
+
+.. automodule:: gcs_client.errors
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.gcs_object.rst b/docs/api/gcs_client.gcs_object.rst
@@ -0,0 +1,7 @@
+gcs_client.gcs_object module
+============================
+
+.. automodule:: gcs_client.gcs_object
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.prefix.rst b/docs/api/gcs_client.prefix.rst
@@ -0,0 +1,7 @@
+gcs_client.prefix module
+========================
+
+.. automodule:: gcs_client.prefix
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.project.rst b/docs/api/gcs_client.project.rst
@@ -0,0 +1,7 @@
+gcs_client.project module
+=========================
+
+.. automodule:: gcs_client.project
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/gcs_client.rst b/docs/api/gcs_client.rst
@@ -0,0 +1,27 @@
+gcs_client package
+==================
+
+.. automodule:: gcs_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+    gcs_client.constants
+
+Submodules
+----------
+
+.. toctree::
+
+   gcs_client.bucket
+   gcs_client.credentials
+   gcs_client.errors
+   gcs_client.gcs_object
+   gcs_client.prefix
+   gcs_client.project
+
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -100,7 +100,7 @@
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+modindex_common_prefix = ['gcs_client.']
 
 # If true, keep warnings as "system message" paragraphs in the built
 # documents.
@@ -273,3 +273,15 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+
+# Group members by type
+autodoc_member_order = 'groupwise'
+
+# Include __init__ methods
+autoclass_content = 'both'
+
+# Autodoc directive flags that should be automatically applied to all autodoc
+# directives.
+autodoc_default_flags = ['members', 'undoc-members', 'inherited-members',
+                         'show-inheritance']
diff --git a/docs/gcs_client.constants.rst b/docs/gcs_client.constants.rst
diff --git a/docs/gcs_client.rst b/docs/gcs_client.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -9,11 +9,12 @@ Welcome to gcs-client's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    readme
    installation
    usage
+   API documentation <api/gcs_client>
    contributing
    authors
    history
@@ -22,6 +23,5 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 
