More Zope compatible autodocumenters for Sphinx.
Project description
waeup.sphinx.autodoc
********************
|bdg-build| | `sources <https://github.com/WAeUP/waeup.sphinx.autodoc>`_ | `issues <https://github.com/WAeUP/waeup.sphinx.autodoc/issues>`_
.. |bdg-build| image:: https://travis-ci.org/WAeUP/waeup.sphinx.autodoc.svg?branch=master
:target: https://travis-ci.org/WAeUP/waeup.sphinx.autodoc
:alt: Build Status
`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 `AttributeError`s you
get (and you cannot tackle otherwise) when using Sphinx_ with
Grok_ projects.
- New ``grokindexes`` autodocumenter documents `grok.Indexes` declarations.
.. contents::
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.
.. _pip: https://pip.pypa.io/
.. _`Sphinx`: http://sphinx-doc.org/
.. _`Zope3`: http://www.zope.org/
.. _`Grok`: http://grok.zope.org/
.. _virtualenv: https://virtualenv.pypa.io/
.. _py.test: https://pytest.org/
.. _tox: https://tox.testrun.org/
********************
|bdg-build| | `sources <https://github.com/WAeUP/waeup.sphinx.autodoc>`_ | `issues <https://github.com/WAeUP/waeup.sphinx.autodoc/issues>`_
.. |bdg-build| image:: https://travis-ci.org/WAeUP/waeup.sphinx.autodoc.svg?branch=master
:target: https://travis-ci.org/WAeUP/waeup.sphinx.autodoc
:alt: Build Status
`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 `AttributeError`s you
get (and you cannot tackle otherwise) when using Sphinx_ with
Grok_ projects.
- New ``grokindexes`` autodocumenter documents `grok.Indexes` declarations.
.. contents::
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.
.. _pip: https://pip.pypa.io/
.. _`Sphinx`: http://sphinx-doc.org/
.. _`Zope3`: http://www.zope.org/
.. _`Grok`: http://grok.zope.org/
.. _virtualenv: https://virtualenv.pypa.io/
.. _py.test: https://pytest.org/
.. _tox: https://tox.testrun.org/
Project details
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
waeup.sphinx.autodoc-0.1.tar.gz
(27.1 kB
view hashes)