More Zope compatible autodocumenters for Sphinx.
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
AttributeErrorsyou get (and you cannot tackle otherwise) when using Sphinx with Grok projects.
- New grokindexes autodocumenter documents
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.
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
which comes with Sphinx automatically.
waeup.sphinx.autodoc provides a new config var and new directives.
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
Sphinx this is a problem, as it assumes that dots in names
denote member objects of a parent object. Lots of
are the result.
This directive renders a
grok.Indexes instance. As
normally an instance of some class and not a class, also any
grok.Indexes ‘class’ will not be recognized as class by stock
waeup.sphinx.autodoc you can describe a
in your code with the new
.. grokindexes:: mymod.MyCatalog Description of MyCatalog
grok.Indexes instances is also possible. For that you
can use the
.. autogrokindexes:: mymod.MyCatalog
Of course, in this case
mymod.MyCatalog must be importable during
For people that want to hack the
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
If download aborts, please keep calm and carry on by retrying.
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).
This Python package is licensed under the GPL v3+.
Copyright (C) 2015 Uli Fouquet and WAeUP Germany.