Skip to main content

Sphinx extension with some autodoc features for any sources

Project description

Extension for gathering reST documentation from any files. This is a documenter from ext.autodoc.

In current state this extension will only insert reST docs from files to target documentation project without auto generation definitions and signatures.

But it simple and clean to make documentation for API and store documentation strings in the source code.

Install

pip install sphinxcontrib-autoanysrc

Usage

Add autoanysrc to extensions list:

extenstion = ['sphinx.ext.autodoc', 'sphinxcontrib.autoanysrc', ]

Example of usage:

.. autoanysrc:: directives
    :src: app/**/*.js
    :analyzer: js

Where:

  • src option is the pattern to list source files where docs are stored

  • analyzer option to determine witch analyzer must be used for processing this files

Directive will iterate over app/**/*.js files and process it line by line.

JSAnalyzer

Search comments blocks starts by /*””” and ends by */ (inspired by Nuulogic/sphinx-jsapidoc).

For example services.js:

/*"""
Services
````````

The function :func:`someService` does a some function.
*/

function someService(href, callback, errback) {
/*"""
.. function:: someService(href, callback[, errback])

    :param string href: An URI to the location of the resource.
    :param callback: Gets called with the object.
    :throws SomeError: For whatever reason in that case.
    :returns: Something.
*/
    return 'some result';
};

TODO

  • encoding option

  • allow internal indent in comment block

  • registering custom analyzers from settings

  • generate signatures like ext.autodoc…

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

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