This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Help us improve Python packaging - Donate today!
Project Description

| 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.

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 History

0.1.1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
waeup.sphinx.autodoc-0.1.1.tar.gz (27.1 kB) Copy SHA256 Checksum SHA256 Source Nov 25, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting