Skip to main content

Sphinx extension for documenting your Pyramid APIs.

Project description

pyramid_autodoc

Sphinx extension for documenting your Pyramid APIs.

Install

pip install pyramid_autodoc

Getting Started

To use pyramid_autodoc you just need to add it to the extensions section of your Sphinx conf.py file:

# conf.py
extensions = [..., 'pyramid_autodoc']

Then just create a new .rst document that uses the pyramid-autodoc directive and provide the path to your Pyramid’s .ini file. Here is an example:

Welcome to my Pyramid app's API docs
====================================

These are the best APIs in the world!

.. autopyramid:: /path/to/development.ini

Then you can just run your sphinx-build command and it will autogenerate API documentation from your Pyramid routes and view docstrings.

We also support using sphinxcontrib-httpdomain format, just use the :format: setting:

Welcome to my Pyramid app's API docs
====================================

These are the best APIs in the world!

.. autopyramid:: /path/to/development.ini
    :format: httpdomain

Ignoring Endpoints

If you have a set of endpoints that you don’t want to group or skip entirely there are a few options you can use:

  • :match-path: - Whitelist only a specific set of paths

  • :skip-path: - Blacklist a specific set of paths

  • :match-module: - Whitelist a set of modules

  • :skip-module: - Blacklist a set of modules

Welcome to my Pyramid app's API docs
====================================

These are the best APIs in the world!

.. autopyramid:: /path/to/development.ini
    :skip-module:
      ^myapp.v1.*
    :match-path:
      ^/data

Linking to Source Code

If you want to link from the endpoint to the source code for the corresponding views and you are using sphinx.ext.viewcode, you can generate links to the source code pages it generates. Alternatively, if your source is on the web, you can generate external links instead.

  • :link-code: - Enable links from endpoints to source code. Assumes sphinx.ext.viewcode is being used unless link-code-pattern is specified.

  • :link-code-pattern: - Pattern URL for generating links to source code. Tokens in the pattern are replaced by the following values.

    • {file} is replaced by the file path, e.g. pyramid_autodoc/utils.py.

    • {lineno_start} is replaced by the beginning line number of the view, e.g. 17.

    • {lineno_end} is replaced by the end line number of the view, e.g. 22.

Welcome to my Pyramid app's API docs
====================================

Links to source code within the docs.

.. autopyramid:: /path/to/development.ini
    :link-code:

Links to source code on GitHub.

.. autopyramid:: /path/to/development.ini
    :link-code:
    :link-code-pattern: https://github.com/SurveyMonkey/pyramid_autodoc/blob/master/{file}#L{lineno_start}-L{lineno_end}

In the last example, a generated link would look like https://github.com/SurveyMonkey/pyramid_autodoc/blob/master/pyramid_autodoc/utils.py#L17-L22.

Project details


Download files

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

Source Distribution

pyramid_autodoc-1.0.0.tar.gz (9.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page