From c88e3cedf44c257a9dc4c00017114fca3f4e58c0 Mon Sep 17 00:00:00 2001 From: John Anderson Date: Mon, 9 Feb 2015 13:50:29 -0800 Subject: [PATCH 1/3] Allow better usage of docs locally. This will default to the rtd theme and introduces tox -e docs for generating docs locally. --- docs/conf.py | 7 +++++++ docs/index.rst | 3 --- tox.ini | 12 +++++++++++- 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 9e95f79bb..25b3d4da5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -262,3 +262,10 @@ # 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()] diff --git a/docs/index.rst b/docs/index.rst index 79167b0ce..cdcddbc1e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,3 @@ - kafka-python ============ @@ -51,11 +50,9 @@ Contents usage api_reference - Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/tox.ini b/tox.ini index 71c89934b..9ce36b18c 100644 --- a/tox.ini +++ b/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,12 @@ deps = mock pylint commands = pylint {posargs: -E kafka test} + +[testenv:docs] +deps = + sphinxcontrib-napoleon + sphinx_rtd_theme + sphinx + +commands = + sphinx-build -b html docs/ docs/_build From e7f52f2aba6fc59c0221ae08fd931fc5276d7eef Mon Sep 17 00:00:00 2001 From: John Anderson Date: Tue, 10 Feb 2015 08:59:28 -0800 Subject: [PATCH 2/3] Use sphinx-apidoc to to generate API docs --- .gitignore | 1 + docs/api_reference.rst | 64 ------------------------------------------ docs/conf.py | 3 +- docs/index.rst | 2 +- tox.ini | 1 + 5 files changed, 5 insertions(+), 66 deletions(-) delete mode 100644 docs/api_reference.rst diff --git a/.gitignore b/.gitignore index 30d663dde..aeeb4740b 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ servers/*/kafka-bin .coverage .noseids docs/_build +docs/apidoc diff --git a/docs/api_reference.rst b/docs/api_reference.rst deleted file mode 100644 index 880466439..000000000 --- a/docs/api_reference.rst +++ /dev/null @@ -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: diff --git a/docs/conf.py b/docs/conf.py index 25b3d4da5..ea223c2c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,6 +30,7 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon', ] @@ -57,7 +58,7 @@ # The short X.Y version. with open('../VERSION') as version_file: version = version_file.read() - + # The full version, including alpha/beta/rc tags. release = version diff --git a/docs/index.rst b/docs/index.rst index cdcddbc1e..e4a9ac70f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,7 +48,7 @@ Contents install tests usage - api_reference + API reference Indices and tables ================== diff --git a/tox.ini b/tox.ini index 9ce36b18c..71565fd08 100644 --- a/tox.ini +++ b/tox.ini @@ -46,4 +46,5 @@ deps = sphinx commands = + sphinx-apidoc -o docs/apidoc/ kafka/ sphinx-build -b html docs/ docs/_build From 70b3af1b3c742973609151f408b60ebb8aff5701 Mon Sep 17 00:00:00 2001 From: John Anderson Date: Tue, 10 Feb 2015 09:29:32 -0800 Subject: [PATCH 3/3] Need to commit apidoc for RTD --- .gitignore | 1 - docs/apidoc/kafka.consumer.rst | 46 ++++++++++++++++++ docs/apidoc/kafka.partitioner.rst | 38 +++++++++++++++ docs/apidoc/kafka.producer.rst | 38 +++++++++++++++ docs/apidoc/kafka.rst | 79 +++++++++++++++++++++++++++++++ docs/apidoc/modules.rst | 7 +++ 6 files changed, 208 insertions(+), 1 deletion(-) create mode 100644 docs/apidoc/kafka.consumer.rst create mode 100644 docs/apidoc/kafka.partitioner.rst create mode 100644 docs/apidoc/kafka.producer.rst create mode 100644 docs/apidoc/kafka.rst create mode 100644 docs/apidoc/modules.rst diff --git a/.gitignore b/.gitignore index aeeb4740b..30d663dde 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,3 @@ servers/*/kafka-bin .coverage .noseids docs/_build -docs/apidoc diff --git a/docs/apidoc/kafka.consumer.rst b/docs/apidoc/kafka.consumer.rst new file mode 100644 index 000000000..8595f9983 --- /dev/null +++ b/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: diff --git a/docs/apidoc/kafka.partitioner.rst b/docs/apidoc/kafka.partitioner.rst new file mode 100644 index 000000000..ea215f142 --- /dev/null +++ b/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: diff --git a/docs/apidoc/kafka.producer.rst b/docs/apidoc/kafka.producer.rst new file mode 100644 index 000000000..bd850bb95 --- /dev/null +++ b/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: diff --git a/docs/apidoc/kafka.rst b/docs/apidoc/kafka.rst new file mode 100644 index 000000000..eb04c35b9 --- /dev/null +++ b/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: diff --git a/docs/apidoc/modules.rst b/docs/apidoc/modules.rst new file mode 100644 index 000000000..db3e580fc --- /dev/null +++ b/docs/apidoc/modules.rst @@ -0,0 +1,7 @@ +kafka +===== + +.. toctree:: + :maxdepth: 4 + + kafka