Metadata-Version: 2.4
Name: repoze-sphinx-autointerface
Version: 1.1.0
Summary: Sphinx extension: auto-generates API docs from Zope interfaces
Author-email: "Tres Seaver, Agendaless Consulting" <tseaver@agendaless.com>
License-Expression: LicenseRef-Repoze-BSD-derived
Project-URL: Repository, https://github.com/repoze/repoze.sphinx.autointerface
Project-URL: Issues, https://github.com/repoze/repoze.sphinx.autointerface/issues
Project-URL: Documentation, https://repozesphinxautointerface.readthedocs.io/en/stable/index.html
Project-URL: Changelog, https://github.com/repoze/repoze.sphinx.autointerface/blob/master/CHANGES.rst
Keywords: web,wsgi,zope,sphinx
Classifier: Development Status :: 6 - Mature
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: zope.interface
Requires-Dist: Sphinx>=4.0
Dynamic: license-file

repoze.sphinx.autointerface README
==================================

.. image:: https://github.com/repoze/repoze.sphinx.autointerface/actions/workflows/ci-tests.yml/badge.svg
    :target: https://github.com/repoze/repoze.sphinx.autointerface/actions/workflows/ci-tests.yml

.. image:: https://img.shields.io/pypi/v/repoze.sphinx.autointerface.svg
    :target: https://pypi.python.org/pypi/repoze.sphinx.autointerface

.. image:: https://img.shields.io/pypi/pyversions/repoze.sphinx.autointerface.svg
    :target: https://pypi.python.org/pypi/repoze.sphinx.autointerface


Overview
--------

Thie package defines an extension for the
`Sphinx <https://www.sphinx-doc.org/en/master/>`_ documentation system.
The extension allows generation of API documentation by introspection of
`zope.interface <https://pypi.org/project/zope.interface/>`_ instances in
code.


Installation
------------

Install via ``pip``:

.. code-block:: bash

    pip install repoze.sphinx.autointerface


Registering the Extension
-------------------------

Add ``repoze.sphinx.autointerface`` to the ``extensions`` list in the
``conf.py`` of the Sphinx documentation for your product.

.. code-block:: python

    extensions = [
        "sphinx.ext.autodoc",
        "sphinx.ext.doctest",
        "repoze.sphinx.autointerface",
    ]


Using the Extension
-------------------

At appropriate points in your document, call out the autodoc interface.

.. code-block:: rst

    .. autointerface:: yourpackage.interfaces.IFoo

Output from the directive includes

- the fully-qualified interface name
- any base interfaces
- the docstring from the interface, rendered as reStructuredText
- the members of the interface (methods and attributes)

  * For each attribute, the output includes the attribute name
    and its description.
  * For each method, the output includes the method name, its signature,
    and its docstring (also rendered as reStructuredText).
