waeup.sphinx.autodoc 0.1.1

More Zope compatible autodocumenters for Sphinx.

| sources | issues

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.

Contents

• Install

• Usage

  • ignore_dot_named_members

  • grokindexes

• Developer Install

  • Running Tests

• License

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.