More Zope compatible autodocumenters for Sphinx.
Project description
waeup.sphinx.autodoc is a Sphinx extension for autodocumenting components/classes specific to Zope3 and Grok.
This project is in early state. Use with care.
Features available yet:
When autodocumenting, ignore components with a dot in their name. This can greatly reduce the number of AttributeErrors you get (and you cannot tackle otherwise) when using Sphinx with Grok projects.
New grokindexes autodocumenter documents grok.Indexes declarations.
Install
This Python package can be installed via pip:
$ pip install waeup.sphinx.autodoc
Normally you will install waeup.sphinx.autodoc with your Zope3 or Grok project. It must be installed in a way, so that Sphinx can find the package. The way depends on your project. For most projects it will be sufficient to add waeup.sphinx.autodoc in the install_requires dict of your setup.py.
Usage
Once installed, you can activate the package in the conf.py of your local Sphinx sources:
# conf.py
#
# ...
#
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'waeup.sphinx.autodoc',
# ...
]
#
# ...
#
Please note, that you also have to activate sphinx.ext.autodoc, which comes with Sphinx automatically.
waeup.sphinx.autodoc provides a new config var and new directives.
ignore_dot_named_members
This config value can be set in the conf.py of your project:
# conf.py # ... ignore_dot_named_members = True # ...
Set to True by default. Avoids sphinx choking on member names with dots in.
If set to True, we skip all member that have a dot in name, i.e. members like grokcore.component.directive. Member names like these are extensively used for instance by grok.
For Sphinx this is a problem, as it assumes that dots in names denote member objects of a parent object. Lots of AttributeErrors are the result.
grokindexes
This directive renders a grok.Indexes instance. As grok.Indexes is normally an instance of some class and not a class, also any grok.Indexes ‘class’ will not be recognized as class by stock Sphinx.
With waeup.sphinx.autodoc you can describe a grok.Indexes instance in your code with the new grokindexes directive:
.. grokindexes:: mymod.MyCatalog
Description of MyCatalog
Autoscanning grok.Indexes instances is also possible. For that you can use the autogrokindexes:
.. autogrokindexes:: mymod.MyCatalog
Of course, in this case mymod.MyCatalog must be importable during Sphinx run.
Developer Install
For people that want to hack the waeup.sphinx.autodoc package itself.
Developers can fork a clone from github:
$ git clone https://github.com/WAeUP/waeup.sphinx.autodoc.git
We recommend to create and activate a virtualenv first:
$ cd waeup.sphinx.autodoc $ virtualenv -p /usr/bin/python2.7 py27 $ source py27/bin/activate (py27) $
We support Python versions 2.6, 2.7.
Now you can create the devel environment:
(py27) $ python setup.py dev
This will fetch test packages (py.test) and other packages needed to run tests. As we need grok and other packages depending of lots of other packages, unfortunately a lot of packages will be downloaded and installed.
If download aborts, please keep calm and carry on by retrying.
Running Tests
After finishing this, you should be able to run tests:
(py27) $ py.test
If you have different Python versions installed, you can use tox for running tests against these:
(py27) $ pip install tox # only once (py27) $ tox
Should run tests in all officially supported Python versions.
(py27) $ tox -e py26
will run tests with a special Python version (here: Python 2.6).
License
This Python package is licensed under the GPL v3+.
Copyright (C) 2015 Uli Fouquet and WAeUP Germany.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for waeup.sphinx.autodoc-0.1.1.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ac31886957a3e87450f0c89cec3e6d69e7e4d4352786c9eab2d69b0f6384cad7 |
|
| MD5 | 1a70274adaea11203c5674419cbac36b |
|
| BLAKE2b-256 | 4c634de198d78114436ce70dd36771419bef2446348d9d8a2ce7149bc41a9e20 |
