Merge pull request #316 from sontek/add_docs_to_tox

Allow better usage of docs locally.

docs/api_reference.rst

@@ -1,64 +0,0 @@
-API Reference
-=============
-
-kafka
------
-.. automodule:: kafka.client
-   :members:
-
-.. automodule:: kafka.codec
-   :members:
-
-.. automodule:: kafka.common
-   :members:
-
-.. automodule:: kafka.conn
-   :members:
-
-.. automodule:: kafka.context
-   :members:
-
-.. automodule:: kafka.protocol
-   :members:
-
-.. automodule:: kafka.util
-   :members:
-
-
-kafka.consumer
---------------
-.. automodule:: kafka.consumer.base
-   :members:
-
-.. automodule:: kafka.consumer.kafka
-   :members:
-
-.. automodule:: kafka.consumer.multiprocess
-   :members:
-
-.. automodule:: kafka.consumer.simple
-   :members:
-
-
-kafka.partitioner
------------------
-.. automodule:: kafka.partitioner.base
-   :members:
-
-.. automodule:: kafka.partitioner.hashed
-   :members:
-
-.. automodule:: kafka.partitioner.roundrobin
-   :members:
-
-
-kafka.producer
---------------
-.. automodule:: kafka.producer.base
-   :members:
-
-.. automodule:: kafka.producer.keyed
-   :members:
-
-.. automodule:: kafka.producer.simple
-   :members:

docs/apidoc/kafka.consumer.rst

@@ -0,0 +1,46 @@
+kafka.consumer package
+======================
+
+Submodules
+----------
+
+kafka.consumer.base module
+--------------------------
+
+.. automodule:: kafka.consumer.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.consumer.kafka module
+---------------------------
+
+.. automodule:: kafka.consumer.kafka
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.consumer.multiprocess module
+----------------------------------
+
+.. automodule:: kafka.consumer.multiprocess
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.consumer.simple module
+----------------------------
+
+.. automodule:: kafka.consumer.simple
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka.consumer
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/kafka.partitioner.rst

@@ -0,0 +1,38 @@
+kafka.partitioner package
+=========================
+
+Submodules
+----------
+
+kafka.partitioner.base module
+-----------------------------
+
+.. automodule:: kafka.partitioner.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.partitioner.hashed module
+-------------------------------
+
+.. automodule:: kafka.partitioner.hashed
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.partitioner.roundrobin module
+-----------------------------------
+
+.. automodule:: kafka.partitioner.roundrobin
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka.partitioner
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/kafka.producer.rst

@@ -0,0 +1,38 @@
+kafka.producer package
+======================
+
+Submodules
+----------
+
+kafka.producer.base module
+--------------------------
+
+.. automodule:: kafka.producer.base
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.producer.keyed module
+---------------------------
+
+.. automodule:: kafka.producer.keyed
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.producer.simple module
+----------------------------
+
+.. automodule:: kafka.producer.simple
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka.producer
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/kafka.rst

@@ -0,0 +1,79 @@
+kafka package
+=============
+
+Subpackages
+-----------
+
+.. toctree::
+
+    kafka.consumer
+    kafka.partitioner
+    kafka.producer
+
+Submodules
+----------
+
+kafka.client module
+-------------------
+
+.. automodule:: kafka.client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.codec module
+------------------
+
+.. automodule:: kafka.codec
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.common module
+-------------------
+
+.. automodule:: kafka.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.conn module
+-----------------
+
+.. automodule:: kafka.conn
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.context module
+--------------------
+
+.. automodule:: kafka.context
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.protocol module
+---------------------
+
+.. automodule:: kafka.protocol
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+kafka.util module
+-----------------
+
+.. automodule:: kafka.util
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: kafka
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/modules.rst

@@ -0,0 +1,7 @@
+kafka
+=====
+
+.. toctree::
+   :maxdepth: 4
+
+   kafka

docs/conf.py

@@ -30,6 +30,7 @@ import os
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinxcontrib.napoleon',
 ]
@@ -262,3 +263,10 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

docs/index.rst

@@ -1,4 +1,3 @@
-
 kafka-python
 ============
 
@@ -49,8 +48,7 @@ Contents
    install
    tests
    usage
-   api_reference
-
+   API reference </apidoc/modules>
 
 Indices and tables
 ==================
@@ -58,4 +56,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

tox.ini

@@ -1,5 +1,6 @@
 [tox]
-envlist = lint, py26, py27, pypy, py33, py34
+envlist = lint, py26, py27, pypy, py33, py34, docs
+
 [testenv]
 deps =
     six
@@ -37,3 +38,13 @@ deps =
     mock
     pylint
 commands = pylint {posargs: -E kafka test}
+
+[testenv:docs]
+deps =
+    sphinxcontrib-napoleon
+    sphinx_rtd_theme
+    sphinx
+
+commands =
+    sphinx-apidoc -o docs/apidoc/ kafka/
+    sphinx-build -b html docs/ docs/_build