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 AttributeErrors you get (and you cannot tackle otherwise) when using Sphinx with Grok projects.
- New grokindexes autodocumenter documents grok.Indexes declarations.
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 sphinx.ext.autodoc, 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 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.
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.
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.
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.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size waeup.sphinx.autodoc-0.1.1.tar.gz (27.1 kB)||File type Source||Python version None||Upload date||Hashes View hashes|
Hashes for waeup.sphinx.autodoc-0.1.1.tar.gz