Champollion

Sphinx extension which provides an automatic way to document javascript code.

Introduction

Champollion is a Sphinx extension which provides a way to parse Javascript source code and produce automatic API documentation from reStructuredText docstrings.

See also

Who is Champollion?

Installing

Note

Using Virtualenv is recommended when evaluating or running locally.

Installation is simple with pip:

pip install champollion

Installing from source

You can also install manually from the source for more control. First obtain a copy of the source by either downloading the zipball or cloning the public repository:

git clone github.com:buddly27/champollion.git

Then you can build and install the package into your current Python environment:

pip install .

If actively developing, you can perform an editable install that will link to the project source and reflect any local changes made instantly:

pip install -e .

Note

If you plan on building documentation and running tests, run the following command instead to install required extra packages for development:

pip install -e .[dev]

Alternatively, just build locally and manage yourself:

python setup.py build

Building documentation from source

Ensure you have installed the ‘extra’ packages required for building the documentation:

pip install -e .[doc]

Then you can build the documentation with the command:

python setup.py build_sphinx

View the result in your browser at:

file:///path/to/champollion/build/doc/html/index.html

Running tests against the source

Ensure you have installed the ‘extra’ packages required for running the tests:

pip install .[test]

Then run the tests as follows:

python setup.py -q test

You can also generate a coverage report when running tests:

python setup.py -q test --addopts "--cov --cov-report=html"

View the generated report at:

file:///path/to/champollion/htmlcov/index.html

Using

Once Champollion installed, add it as an extension to your Sphinx configuration file and indicate the path to the Javascript source code:

# conf.py
extensions = [
    "champollion"
]

js_source = "./relative/path/to/example"

All Javascript files within the js_source structure path is parsed when the sphinx builder is initiated, and all relevant information is fetched within a configuration environment which includes the description for each element.

See also

Documenting Javascript

See also

Using Configuration

For all directives, only one argument must be given which represents the identifier of the element to document. This identifier depends on the file structure hierarchy.

Let’s consider the following example:

# conf.py
js_source = "./example"

The identifier of a class named TestClass included in ./example/module/test.js will be example.module.test.TestClass. This class element can be documented as follow:

*****************************
example.module.test.TestClass
*****************************

.. js:autoclass:: example.module.test.TestClass

Note

Champollion add all directives to the Javascript domain. The js: prefix must then be used for each directive, or the following line should be added to the Sphinx configuration file:

# conf.py
primary_domain = "js"

See also

Using Directives

Documenting Javascript

Contrarily to Python which has some high-level conventions for code documentation (expressed in PEP 257), there is no standard equivalent for the concept of docstrings in the Javascript world.

Champollion is using the same convention as JSDoc, which define a docstring as a specific comment block starting with /**:

/**
 * Return a temperature converted from Fahrenheit to Celsius.
 *
 * :param f: integer
 * :return: integer
 */
function toCelsius(f) {
    return (5/9) * (f-32);
}

The docstring can also be in one line:

/** This is a description of the foo variable. */
const foo = 42;

Each element description must use the reStructuredText language.

Using Directives

Using automodule

Document nested elements from a module represented by a file or a index.js file within a folder:

example/
 |- index.js
 `- test.js

Two modules are available in the example above: example and example.test

.. js:automodule:: example

The available options are:

• members:

  This option can be boolean if no arguments are given to indicate that all members should be documented, or a white list of member names to display.

• skip-description:

  Indicate whether the module description should be skipped.

• skip-data-value:

  Indicate whether data values within the module should be skipped.

• skip-attribute-value:

  Indicate whether attribute values within the module should be skipped.

• undoc-members:

  Indicate whether members with no docstrings should be displayed.

• private-members:

  Indicate whether private members (with a name starting with an underscore) should be displayed.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether each import statement display within the module should be indicated with partial import.

See also

Using automodule options

Using autodata

Document a variable declaration using one of the following way:

• const
• let
• var

Example:

/** PI Mathematical Constant. */
const PI = 3.14159265359;

.. js:autodata:: example.PI

The available options are:

• alias:

  String element to replace the data name.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether the data import statement display should be indicated with partial import if the data element is exported.

• skip-value:

  Indicate whether data value should be skipped.

Using autofunction

Document a function declaration using one of the following way:

• function
• function expression
• arrow-type function
• function* statement
• function* expression

Example:

/**
 * Return a distance converted from Meter to Miles.
 *
 * :param d: integer
 * :return: integer
 */
const toMiles = (d) => {
    return d * 0.00062137;
}

.. js:autofunction:: example.toMiles

The available options are:

• alias:

  String element to replace the function name.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether the function import statement display should be indicated with partial import if the function element is exported.

Warning

These function declaration statements are not supported at the moment:

• Function object
• GeneratorFunction object
• async function
• async function expression

Using autoclass

Document a class declaration using one of the following way:

• class
• class expression

Example:

/*
 * A Square class declaration.
 */
class Square extends Polygon {

    /** Square ID. */
    static name = 'Square';

    /** Construct the Square object. */
    constructor(length) {
        super(length, length);
    }

    /**
     * Compute and get the area from the square.
     *
     * :return: double
     */
    get area() {
        return this.height * this.width;
    }

    /**
     * Indicate whether a polygon is a square.
     *
     * :param polygon: :class:`Polygon` object
     * :return: boolean
     */
    static isSquare(polygon) {
        return (polygon.height === polygon.width);
    }
}

.. js:autoclass:: example.Square

The available options are:

• members:

  This option can be boolean if no arguments are given to indicate that all members should be documented, or a white list of member names to display.

• skip-constructor:

  Indicate whether the constructor method should be displayed if available.

• skip-attribute-value:

  Indicate whether attribute values within the class should be skipped.

• undoc-members:

  Indicate whether members with no docstrings should be displayed.

• private-members:

  Indicate whether private members (with a name starting with an underscore) should be displayed.

• alias:

  String element to replace the class name.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether the class import statement display should be indicated with partial import if the class element is exported.

Warning

The documentation of nested elements within a variable is not supported

Example:

var Rectangle = {
    constructor(height, width) {
        this.height = height;
        this.width = width;
    }
};

See also

Using autoclass options

Using automethod

Document a method using one of the following way:

• getter
• setter
• arrow-type method
• static

Example:

From the class example above, the static method isSquare would be documented as follow:

.. js:automethod:: example.Square.isSquare

Warning

These method declaration statements are not supported at the moment:

• method generator
• async method

Using autoattribute

Document a class attribute using one of the following way:

• static

Example:

From the class example above, the static attribute name would be documented as follow:

.. js:autoattribute:: example.Square.name

The available options are:

• skip-value:

  Indicate whether attribute value should be skipped.

Using Configuration

Some configuration values are available to provide the Javascript source environment or to automatically add options to the directives.

These configuration must be added to the Sphinx configuration file.

Using code source

Provide a path to the Javascript source code that will be analysed by champollion.parser:

# conf.py
js_source = "/path/to/code"

An environment will be generated when the builder-inited event is emitted.

It is also possible to provide several paths:

# conf.py
js_sources = ["/path/to/code1", "/path/to/code2"]

Using environment

Provide a Javascript environment dictionary which must be in the form of the champollion.parser.fetch_environment() returned value:

# conf.py
js_environment = {
    "module": {},
    "file": {}
    "class": {},
    "method": {},
    "attribute": {},
    "function": {},
    "data": {}
}

Using autoclass options

Provide a list of options to apply automatically for all autoclass directives:

# conf.py
js_class_options = ["members", "skip-constructor", "undoc-members"]

This configuration only accept the following boolean options:

• members (When not used as a ‘white list’)
• skip-constructor
• skip-attribute-value
• undoc-members
• private-members
• force-partial-import

Using automodule options

Provide a list of options to apply automatically for all automodule directives:

# conf.py
js_module_options = ["undoc-members", "private-members"]

This configuration only accept the following boolean options:

• members (When not used as a ‘white list’)
• skip-description
• skip-data-value
• skip-attribute-value
• undoc-members
• private-members
• force-partial-import

API Reference

champollion

champollion.setup(app)

Register callbacks and directives.

champollion.fetch_javascript_environment(app)

Fetch the Javascript environment from the app configuration.

If the js_environment configuration is not provided, attempt to parse the path provided via the js_source or js_sources configuration value.

This function is called with the builder-inited Sphinx event, emitted when the builder object is created.

See also

Using Configuration

champollion.directive

Directives to generate a Javascript API documentation.

champollion.directive.base

class champollion.directive.base.BaseDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Base class for Javascript object directive.

required_arguments = 1

Only the object id argument is required

optional_arguments = 0

No optional argument is available

has_content = False

Content is automatically generated and can not be manually entered

allow_nesting = False

Nested element is automatically generated and can not be manually entered

display_prefix = None

No prefix is displayed right before the documentation entry

run()

Run the directive.

generate_import_statement(environment, module_environment, force_partial_import=False)

Return import statement generated from environment and module_environment.

The import statement will be generated only if the element is exported and the usage of partial import will depend whether the element is exported as default.

force_partial_import indicate whether the usage of partial import should be used even if the element is exported as default.

Warning

The statement is using Javascript ES6 import keyword

Example:

import element from "module"
import {partialElement} from "module"

generate_description(environment)

Return description generated from environment.

champollion.directive.js_class

class champollion.directive.js_class.AutoClassDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to render Javascript class documentation.

The unique argument should be the identifier of the class element.

.. js:autoclass:: module.AwesomeClass

The available options are:

• members:

  This option can be boolean if no arguments are given to indicate that all members should be documented, or a white list of member names to display.

• skip-constructor:

  Indicate whether the constructor method should be displayed if available.

• skip-attribute-value:

  Indicate whether attribute values within the class should be skipped.

• undoc-members:

  Indicate whether members with no docstrings should be displayed.

• private-members:

  Indicate whether private members (with a name starting with an underscore) should be displayed.

• alias:

  String element to replace the class name.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether the class import statement display should be indicated with partial import if the class element is exported.

See also

Using autoclass

See also

Using autoclass options

has_arguments = True

Javascript class is callable

objtype = 'class'

Define the Object type

option_spec = {'alias': <function unchanged_required>, 'force-partial-import': <function <lambda>>, 'members': <function _parse_members>, 'module-alias': <function unchanged_required>, 'module-path-alias': <function unchanged_required>, 'private-members': <function <lambda>>, 'skip-attribute-value': <function <lambda>>, 'skip-constructor': <function <lambda>>, 'undoc-members': <function <lambda>>}

classes options

handle_signature(signature, node)

Update the signature node.

before_content()

Update the content.

Compute the description and import statement if available, and generate the class nested directive elements to integrate to the content.

class champollion.directive.js_class.AutoMethodDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to render Javascript class method documentation.

The unique argument should be the identifier of the class method element.

.. js:automethod:: module.AwesomeClass.awesomeMethod

See also

Using automethod

has_arguments = True

Javascript method is callable

objtype = 'method'

Define the Object type

handle_signature(signature, node)

Update the signature node.

before_content()

Update the content.

Compute the description if available.

class champollion.directive.js_class.AutoAttributeDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to render Javascript class attribute documentation.

The unique argument should be the identifier of the class attribute element.

.. js:autoattribute:: module.AwesomeClass.DATA

The available options are:

• skip-value:

  Indicate whether attribute value should be skipped.

See also

Using autoattribute

has_arguments = False

Javascript data are not callable

objtype = 'attribute'

Define the Object type

option_spec = {'skip-value': <function <lambda>>}

data options

handle_signature(signature, node)

Update the signature node.

before_content()

Update the content.

Compute the description if available.

champollion.directive.js_data

class champollion.directive.js_data.AutoDataDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to render Javascript data documentation.

The unique argument should be the identifier of the data element.

.. js:autodata:: module.DATA

The available options are:

• alias:

  String element to replace the data name.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether the data import statement display should be indicated with partial import if the data element is exported.

• skip-value:

  Indicate whether data value should be skipped.

See also

Using autodata

has_arguments = False

Javascript data are not callable

objtype = 'data'

Define the Object type

option_spec = {'alias': <function unchanged_required>, 'force-partial-import': <function <lambda>>, 'module-alias': <function unchanged_required>, 'module-path-alias': <function unchanged_required>, 'skip-value': <function <lambda>>}

data options

handle_signature(signature, node)

Update the signature node.

before_content()

Update the content.

Compute the description and import statement if available.

champollion.directive.js_function

class champollion.directive.js_function.AutoFunctionDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to render Javascript function documentation.

The unique argument should be the identifier of the function element.

.. js:autofunction:: module.doSomething

The available options are:

• alias:

  String element to replace the function name.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether the function import statement display should be indicated with partial import if the function element is exported.

See also

Using autofunction

has_arguments = True

Javascript function is callable

objtype = 'function'

Define the Object type

option_spec = {'alias': <function unchanged_required>, 'force-partial-import': <function <lambda>>, 'module-alias': <function unchanged_required>, 'module-path-alias': <function unchanged_required>}

function options

handle_signature(signature, node)

Update the signature node.

before_content()

Update the content.

Compute the description and import statement if available.

champollion.directive.js_module

class champollion.directive.js_module.AutoModuleDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive to render Javascript module documentation.

The unique argument should be the identifier of the module element.

.. js:automodule:: module.test

The available options are:

• members:

  This option can be boolean if no arguments are given to indicate that all members should be documented, or a white list of member names to display.

• skip-description:

  Indicate whether the module description should be skipped.

• skip-data-value:

  Indicate whether data values within the module should be skipped.

• skip-attribute-value:

  Indicate whether attribute values within the module should be skipped.

• undoc-members:

  Indicate whether members with no docstrings should be displayed.

• private-members:

  Indicate whether private members (with a name starting with an underscore) should be displayed.

• module-alias:

  String element to replace the module name.

• module-path-alias:

  String element to replace the module path.

• force-partial-import:

  Indicate whether each import statement display within the module should be indicated with partial import.

See also

Using automodule

See also

Using automodule options

required_arguments = 1

Only the object id argument is required

optional_arguments = 0

No optional argument is available

has_content = False

Content is automatically generated and can not be manually entered

allow_nesting = False

Nested element is automatically generated and can not be manually entered

option_spec = {'force-partial-import': <function <lambda>>, 'members': <function _parse_members>, 'module-alias': <function unchanged_required>, 'module-path-alias': <function unchanged_required>, 'private-members': <function <lambda>>, 'skip-attribute-value': <function <lambda>>, 'skip-data-value': <function <lambda>>, 'skip-description': <function <lambda>>, 'undoc-members': <function <lambda>>}

module options

run()

Run the directive.

generate_members(module_environment, options, whitelist_names=None)

Generate a list of member nodes from module_environment

options is the dictionary of module options that can affect the display of members

whitelist_names is an optional list of element names that should be displayed exclusively.

champollion.directive.rst_generator

champollion.directive.rst_generator.get_rst_class_elements(environment, module_name, module_path_name, whitelist_names=None, undocumented_members=False, private_members=False, force_partial_import=False, skip_attribute_value=False, rst_elements=None)

Return reStructuredText from class elements within environment.

module_name is the module alias that should be added to each directive.

module_path_name is the module path alias that should be added to each directive.

whitelist_names is an optional list of element names that should be displayed exclusively.

undocumented_members indicate whether undocumented element should be displayed.

private_members indicate whether elements starting with an underscore should be displayed.

force_partial_import indicate whether the import statement should force the partial import display if necessary.

skip_attribute_value indicate whether attribute value within the class should not be displayed.

rst_elements can be an initial dictionary that will be updated and returned.

champollion.directive.rst_generator.get_rst_attribute_elements(class_environment, whitelist_names=None, blacklist_ids=None, undocumented_members=False, private_members=False, skip_value=False, rst_elements=None)

Return reStructuredText from class attribute elements within class_environment.

whitelist_names is an optional list of element names that should be displayed exclusively.

blacklist_ids is an optional list of element identifiers that should not be displayed.

undocumented_members indicate whether undocumented element should be displayed.

private_members indicate whether elements starting with an underscore should be displayed.

skip_value indicate whether the value should not be displayed.

rst_elements can be an initial dictionary that will be updated and returned.

champollion.directive.rst_generator.get_rst_method_elements(class_environment, whitelist_names=None, skip_constructor=False, undocumented_members=False, private_members=False, rst_elements=None)

Return reStructuredText from class method elements within class_environment.

whitelist_names is an optional list of element names that should be displayed exclusively.

skip_constructor indicate whether the class constructor should be displayed.

undocumented_members indicate whether undocumented element should be displayed.

private_members indicate whether elements starting with an underscore should be displayed.

rst_elements can be an initial dictionary that will be updated and returned.

champollion.directive.rst_generator.get_rst_function_elements(environment, module_name, module_path_name, whitelist_names=None, undocumented_members=False, private_members=False, force_partial_import=False, rst_elements=None)

Return reStructuredText from function elements within environment.

module_name is the module alias that should be added to each directive.

module_path_name is the module path alias that should be added to each directive.

whitelist_names is an optional list of element names that should be displayed exclusively.

undocumented_members indicate whether undocumented element should be displayed.

private_members indicate whether elements starting with an underscore should be displayed.

force_partial_import indicate whether the import statement should force the partial import display if necessary.

rst_elements can be an initial dictionary that will be updated and returned.

champollion.directive.rst_generator.get_rst_data_elements(environment, module_name, module_path_name, whitelist_names=None, blacklist_ids=None, undocumented_members=False, private_members=False, force_partial_import=False, skip_value=False, rst_elements=None)

Return reStructuredText from data elements within environment.

module_name is the module alias that should be added to each directive.

module_path_name is the module path alias that should be added to each directive.

whitelist_names is an optional list of element names that should be displayed exclusively.

blacklist_ids is an optional list of element identifiers that should not be displayed.

undocumented_members indicate whether undocumented element should be displayed.

private_members indicate whether elements starting with an underscore should be displayed.

force_partial_import indicate whether the import statement should force the partial import display if necessary.

skip_value indicate whether the value should not be displayed.

rst_elements can be an initial dictionary that will be updated and returned.

champollion.directive.rst_generator.get_rst_export_elements(file_environment, environment, module_name, module_path_name, skip_data_value=False, skip_attribute_value=False, rst_elements=None)

Return reStructuredText from exported elements within file_environment.

environment is the full Javascript environment processed in parser.

module_name is the module alias that should be added to each directive.

module_path_name is the module path alias that should be added to each directive.

skip_data_value indicate whether data value should not be displayed.

skip_attribute_value indicate whether attribute value should not be displayed.

rst_elements can be an initial dictionary that will be updated and returned.

champollion.directive.rst_generator.get_rst_default_from_file_environment(file_environment, alias, module_name, module_path_name, skip_data_value=False, skip_attribute_value=False)

Return reStructuredText from default element in file_environment.

alias is the name that should replace the element name.

module_name is the module alias that should replace the element module name.

module_path_name is the module path alias that should be added to each directive.

skip_data_value indicate whether data value should not be displayed.

skip_attribute_value indicate whether attribute value should not be displayed.

Warning

Return None if no default is found in the file.

champollion.directive.rst_generator.get_rst_name_from_file_environment(name, file_environment, alias, module_name, module_path_name, skip_data_value=False, skip_attribute_value=False)

Return reStructuredText element in file_environment from name.

alias is the name that should replace the element name.

module_name is the module name that should replace the element module name.

module_path_name is the module path alias that should be added to each directive.

skip_data_value indicate whether data value should not be displayed.

skip_attribute_value indicate whether attribute value should not be displayed.

Warning

Return None if the element is not found in the file.

champollion.directive.rst_generator.rst_generate(directive, element_id, alias=None, module_alias=None, module_path_alias=None, extra_options=None)

Generate StringList from directive and element_id.

directive is one of the directive added to the Javascript domain by this sphinx extension.

element_id is an element ID returned by the parser.

alias is the name that should replace the element name.

module_alias is the module name that should replace the element module name.

module_path_alias is the module path that should replace the element module path.

extra_options can be a list of extra options to add to the directive.

champollion.directive.rst_generator.rst_string(expression='')

Return StringList from expression.

champollion.parser

Parser to fetch_environment all information from a Javascript API in order to document each element from a simple identifier.

champollion.parser.fetch_environment(path)

Return Javascript environment dictionary from path structure.

Raises OSError if the directory is incorrect.

The environment is in the form of:

{
    "module": {
        "module.id": {
            "id": "module.id",
            "name": "module_name",
            "file_id": "file/id/index.js"
            "description": "A module."
            ...
        },
        ...
    },
    "file": {
        "file/id/index.js": {
            "id": "file/id/index.js",
            "module_id": "module_id",
            "content": "...",
            ...
        },
        ...
    },
    "class": {
        "class_id": {
            "id": "class_id",
            "module_id": "module_id"
            "description": "A class."
            ...
        },
        ...
    },
    "method": {
        "method_id": {
            "id": "method_id",
            "class_id": "class_id",
            "module_id": "module_id",
            "description": "A method."
            ...
        },
        ...
    },
    "attribute": {
        "attribute_id": {
            "id": "attribute_id",
            "class_id": "class_id",
            "module_id": "module_id",
            "description": "An attribute."
            ...
        },
        ...
    },
    "function": {
        "function_id": {
            "id": "function_id",
            "module_id": "module_id",
            "description": "A function."
            ...
        },
        ...
    },
    "data": {
        "data_id": {
            "id": "data_id",
            "module_id": "module_id",
            "description": "A variable."
            ...
        },
        ...
    }
}

champollion.parser.helper

champollion.parser.helper.filter_comments(content, filter_multiline_comment=True, keep_content_size=False)

Return content without the comments.

If filter_multiline_comment is set to False, only the one line comment will be filtered out.

If keep_content_size is set to True, the size of the content is preserved.

Note

The filtered content keep the same number of lines as the original content.

See also

https://www.w3schools.com/js/js_comments.asp

champollion.parser.helper.collapse_all(content, filter_comment=False)

Return tuple of content with the top level elements only and dictionary containing the collapsed content associated with the line number.

If filter_comment is set to True, all comment are removed from the content before collapsing the elements. The collapsed content dictionary preserve the comments.

Note

The content with collapsed elements keep the same number of lines as the original content.

champollion.parser.helper.get_docstring(line_number, lines)

Return docstrings for an element at a specific line_number.

Loop into the file lines in reverse, starting from the element’s line_number in order to parse the docstring if available.

The docstring must be in the form of:

/**
 * Class doc.
 *
 * Detailed description.
 */
class AwesomeClass {
   ...
}

Which will return the following result:

"Class doc.\n\nDetailed description."

The docstring can also fit on one line, in the form of:

/** Class doc. */
class AwesomeClass {
   ...
}

champollion.parser.js_class

champollion.parser.js_class.fetch_environment(content, module_id)

Return class environment dictionary from content.

module_id represent the identifier of the module.

The environment is in the form of:

{
    "moduleName.AwesomeClass": {
        "id": "module.AwesomeClass",
        "name": "AwesomeClass",
        "parent": "MotherClass",
        "line": 42,
        "description": "Class doc.\n\nDetailed description."

        "id": "moduleName.AwesomeClass",
        "module_id": "moduleName",
        "exported": False,
        "default": False,
        "name": "AwesomeClass",
        "parent": None,
        "line_number": 2,
        "description": "Class doc.\n\nDetailed description."
        "method": {
            "moduleName.AwesomeClass.awesomeMethod": {
                ....
            }
        },
        "attribute": {
            "moduleName.AwesomeClass.DATA": {
                ....
            }
        }
    },
    ...
}

champollion.parser.js_class.fetch_methods_environment(content, class_id, line_number=0)

Return function environment dictionary from content.

class_id represent the identifier of the method class.

line_number is the first line number of content.

The environment is in the form of:

{
    "moduleName.AwesomeClass.awesomeMethod": {
        "id": "moduleName.AwesomeClass.awesomeMethod",
        "class_id": "moduleName.AwesomeClass",
        "module_id": "moduleName",
        "name": "awesomeMethod",
        "prefix": "get",
        "arguments": ["argument1", "argument2"],
        "line_number": 5,
        "description": "Method doc.\n\nDetailed description."
    }
}

champollion.parser.js_class.fetch_attribute_environment(content, class_id, line_number=0)

Return attribute environment dictionary from content.

class_id represent the identifier of the attribute class.

line_number is the first line number of content.

The environment is in the form of:

{
    "moduleName.AwesomeClass.DATA": {
        "id": "moduleName.AwesomeClass.DATA",
        "class_id": "moduleName.AwesomeClass",
        "module_id": "moduleName",
        "name": "DATA",
        "prefix": "static",
        "value": "42",
        "line_number": 8,
        "description": "Attribute doc.\n\nDetailed description."
    }
}

champollion.parser.js_data

champollion.parser.js_data.fetch_environment(content, module_id)

Return data environment dictionary from content.

module_id represent the identifier of the module.

The environment is in the form of:

{
    "moduleName.DATA": {
        "id": "moduleName.DATA",
        "module_id": "moduleName",
        "exported": False,
        "default": False,
        "name": "DATA",
        "value": "42",
        "type": "const",
        "line_number": 2,
        "description": "Variable doc.\n\nDetailed description."
    }
}

champollion.parser.js_file

champollion.parser.js_file.fetch_environment(file_path, file_id, module_id)

Return file environment dictionary from file_path.

file_id represent the identifier of the file.

module_id represent the identifier of the module.

Update the environment if available and return it as-is if the file is not readable.

The environment is in the form of:

{
    "id": "module/test/index.js",
    "module_id": "module.test",
    "name": "index.js",
    "path": "/path/to/module/test/index.js",
    "content": "'use strict'\n\n...",
    "description": "File description",
    "export": {
        "module.test.exported_element": {
            "id": "module.test.exported_element",
            "module": "module.test.from_module",
            "description": "An exported element",
            ...
        },
        ...
    },
    "import": {
        "module.test.imported_element": {
            "id": "module.test.imported_element",
            "module": "module.test.from_module",
            ...
        },
        ...
    },
    "class": {
        "class_id": {
            "id": "class_id",
            "module_id": "module_id"
            "description": "A class."
            ...
        },
        ...
    },
    "data": {
        "data_id": {
            "id": "data_id",
            "module_id": "module_id",
            "description": "A variable."
            ...
        },
        ...
    },
    "function": {
        "function_id": {
            "id": "function_id",
            "module_id": "module_id",
            "description": "A function."
            ...
        },
        ...
    }
}

champollion.parser.js_file.fetch_file_description(content)

Return file description from content.

The description must be in a docstring which should be defined at the very beginning of the file. It can only be preceded by one line comments.

It must be in the form of:

/**
 * File description.
 *
 * A detailed description of the file.
 *
 */

Return None if no description is available.

champollion.parser.js_file.update_from_exported_elements(environment, export_environment)

Update environment with exported elements from export_environment.

For instance, the element environment might not be exported, but an exported element is found that can be linked to this element.

// Element in the environment
function doSomething(arg1, arg2) {
    console.log("Hello World")
}

// Element in the export environment
export {doSomething};

In the example above, the function doSomething is previously fetched without the exported attribute, so it will be added to it.

The entry will then be removed from the export_environment.

Warning

Both input environments are mutated.

champollion.parser.js_file.fetch_import_environment(content, module_id)

Return import environment dictionary from content.

module_id represent the identifier of the module.

The environment is in the form of:

{
    "module.test.imported_element": {
        "id": "module.test.imported_element",
        "module": "module.test.from_module",
        "name": "imported_element",
        "alias": None,
        "partial": False
    },
    ...
}

champollion.parser.js_file.fetch_export_environment(content, module_id)

Return export environment dictionary from content.

module_id represent the identifier of the module.

The environment is in the form of:

{
    "module.test.exported_element": {
        "id": "module.test.exported_element",
        "module": "module.test.from_module",
        "name": "exported_element",
        "alias": None,
        "partial": True,
        "description": None,
        "default": False,
        "line_number": 5,
    },
    ...
}

champollion.parser.js_function

champollion.parser.js_function.fetch_environment(content, module_id)

Return function environment dictionary from content.

module_id represent the identifier of the module.

The environment is in the form of:

{
    "moduleName.doSomething": {
        "id": "moduleName.doSomething",
        "module_id": "moduleName",
        "exported": False,
        "default": False,
        "name": "doSomething",
        "anonymous": False,
        "generator": False,
        "arguments": ["argument1", "argument2"],
        "line_number": 2,
        "description": "Function doc.\n\nDetailed description."
    }
}

champollion.parser.js_module

champollion.parser.js_module.fetch_environment(file_id, files=None, module_names=None)

Return module environment dictionary from file_id.

file_id represent the identifier of the file.

files is an optional list of the other file names stored in the same directory as the one analyzed.

module_names is an optional list of all the other module name previously fetched to help determine the module name of the current file.

The environment is in the form of:

{
    "id": "module.test",
    "name": test,
    "file_id": "module/test/index.js"
}

champollion.viewcode

class champollion.viewcode.ViewCode

Helper class to display the code for each Javascript module found and link it to the documentation.

js_modules = None

Store the modules elements to link to the code

classmethod add_source_code_links(app, doctree)

Parse doctree and add source code link when available.

Create temporary ‘js_modules’ in app builder environment to store all module information which will be used to create the code page links.

This function is called with the doctree-read Sphinx event, emitted when a doctree has been parsed and read by the environment, and is about to be pickled

classmethod create_code_pages(app)

Create all code pages and the links to the documentation.

This function is called with the html-collect-pages Sphinx event, emitted when the HTML builder is starting to write non-document pages.

classmethod create_code_page_index(app)

Create page index regrouping all code page links.

classmethod create_missing_code_link(app, env, node, content_node)

Resolve all ‘[source]’ links in Api documentation pages.

This function is called with the missing-reference Sphinx event, emitted when a cross-reference to a Python module or object cannot be resolved.

Release Notes

1.0.0

31 May 2020

• new

  directiveUpdated js:automodule to inherit from docutils.parsers.rst.Directive instead of sphinx.directives.Directive so it can work with Sphinx >= 1.8.

0.8.1

23 September 2018

• fixed

  Excluded the Sphinx requirement version from 1.8 as Directive class is removed from the sphinx.directives module.

  See also

  Sphinx Release 1.8.0

0.8.0

14 July 2018

• new

  directiveAdded :skip-value: option to the js:autodata directive to prevent displayed the data value.

• new

  directiveAdded :skip-value: option to the js:autoattribute directive to prevent displayed the attribute value.

• new

  directiveAdded :skip-attribute-value: option to the js:autoclass directive to prevent displayed all attribute values within the class.

• new

  directiveAdded :skip-attribute-value: option to the js:automodule directive to prevent displayed all attribute values within the module.

• new

  directiveAdded :skip-data-value: option to the js:automodule directive to prevent displayed all data values within the module.

0.7.2

6 July 2018

• fixed

  Fixed package version issue.

0.7.1

6 July 2018

• fixed

  unit-testsUpdated Travis configuration to run unit-tests for Python 3.6.

0.7.0

6 July 2018

• new

  configurationAdded js_sources global configuration value which can contains several paths to Javascript source codes to parse.

• fixed

  javascript-parserFixed champollion.parser.helper.get_docstring() to ensure that a docstring is not associated with an element when too many blank lines separate the docstring from the function.

0.6.0

3 July 2017

• new

  javascript-parserAdded champollion.parser.js_file.fetch_file_description() to return description included in the docstring defined at the very beginning of the file.

• changed

  javascript-parserUpdated champollion.parser.js_file.fetch_environment() to include the file description in the environment.

• new

  directiveUpdated js:automodule to display the module description.

• new

  directiveAdded :members: option to the js:automodule directive to provide a way to document all or part of the members contained within a class.

  Note

  This option can be set automatically via the js_module_options configuration

  Warning

  By default, only the description of the module will be displayed.

• new

  directiveAdded :skip-description: option to the js:automodule directive to provide a way to skip the module description.

  Note

  This option can be set automatically via the js_module_options configuration

• new

  javascript-parserAdded module path to the module environment returned by champollion.parser.js_module.fetch_environment()

• changed

  directiveUpdated all directives to use the module path when displaying the import statement:

  import {Element} from "example/module"
  

• new

  directiveAdded :module-path-alias: options to all directives to modify the path of the module from the element to display.

• fixed

  javascript-parserUpdated the regular expression in the data parser to recognize values spread over several lines:

  const DATA = {
      key1: 'value1',
      key2: 'value2',
      key3: 'value3',
  };
  

  Warning

  This update requires that all documented data statements end with a semi-colon.

• fixed

  javascript-parserUpdated the regular expression in the attribute parser to recognize values spread over several lines:

  class AwesomeClass {
      static DATA = {
          key1: 'value1',
          key2: 'value2',
          key3: 'value3',
      }
  }
  

  Warning

  This update requires that all documented attribute statements end with a semi-colon.

• fixed

  javascript-parserUpdated the regular expressions in the method parser to recognize arguments spread over several lines:

  class AwesomeClass {
      method(
          argument1,
          argument2,
          argument3,
      ) {
          console.log('Hello World')
      }
  }
  

0.5.2

29 June 2017

• fixed

  Updated the Sphinx dependency version to 1.6.2 as module and method directives where missing from the Javascript domain in older versions.

  See also

  Sphinx Release Notes

• changed

  Updated pytest dependency version to 3.0.0

0.5.1

25 June 2017

• fixed

  Added PyPi and RTD badges to the README page

0.5.0

25 June 2017

• new

  configurationAdded js_module_options global configuration value which contains a list of class directive boolean option activated by default.

  js_module_options=['undoc-members', 'private-members']
  

• new

  documentationAdded configuration documentation.

0.4.2

14 June 2017

• fixed

  directiveEnsured that each element documented can be targeted by the standard Javascript roles

• changed

  javascript-parserAdded js_environment global configuration value which will be filled automatically from the js_source global configuration via the champollion.parser if not provided.

  This ensure that the documentation is rebuilt when the source code is modified.

0.4.1

11 June 2017

• fixed

  Removed implicit relative imports within packages for compatibility with Python 3.

0.4.0

11 June 2017

• new

  javascript-parserAdded champollion.parser.js_file.fetch_import_environment() to fetch elements imported from different modules if possible:

  import {element as alias} from "./module"
  import * from "./module"
  

• new

  javascript-parserAdded champollion.parser.js_file.fetch_export_environment() to fetch elements exported from different modules if possible:

  export {element as alias} from "./module"
  export * from "./module"
  

• new

  javascript-parserAdded champollion.parser.js_file.update_from_exported_elements() to regroup the exported element within a file environment if possible.

• new

  directiveAdded :alias: options to all directives (except js:automodule ) to modify the name of the element to display.

• new

  directiveAdded :module-alias: options to all directives to modify the name of the module from the element to display.

• new

  directiveAdded :force-partial-import: options to all directives to force the display of partial import if the element is exported. On the js:automodule, this options is applied to all nested elements.

• new

  javascript-parserAdded more unit tests for champollion.parser

• fixed

  javascript-parserFixed class parser to recognize class expression assigned to let and var variables.

0.3.3

7 June 2017

• fixed

  javascript-parserFixed unit tests for function parser

0.3.2

7 June 2017

• changed

  javascript-parserAdded support for function expression in function parser.

• changed

  directivejavascript-parserAdded support for function generator in function parser and AutoFunctionDirective.

• fixed

  javascript-parserFixed function parser to recognize arrow-type function expression assigned to let and var variables.

• fixed

  directivejavascript-parserFixed function parser and AutoFunctionDirective to support anonymous function.

• changed

  documentationUpdate usage documentation.

0.3.1

6 June 2017

• fixed

  javascript-parserFix champollion.parser.js_data.fetch_environment() to preserve the data value with all of its potential nested elements.

  Format the value on one line to ease the display.

• fixed

  directiveAs an arrow-type function can be also be considered as a variable, ensure that the js:automodule and js:autoclass directives use the AutoFunctionDirective and AutoMethodDirective in priority when available.

0.3.0

5 June 2017

• new

  directiveAdded AutoModuleDirective directive to generate the documentation from a module id representing a module (a file name without the ‘.js’ extension or a directory with an ‘index.js’ file) parsed within the Javascript source code.

• new

  directiveAdded :undoc-members: option to the js:automodule directive to provide a way to document the module members without docstrings.

• new

  directiveAdded :private-members: option to the js:automodule directive to provide a way to document the private module members.

• new

  documentationAdded usage documentation.

• fixed

  documentationFix the zipball link in the installation documentation.

0.2.0

4 June 2017

• new

  directiveAdded :members: option to the js:autoclass directive to provide a way to document all or part of the members contained within a class.

• new

  directiveAdded :skip-constructor: option to the js:autoclass directive to provide a way to filter a class constructor in the documentation generated.

• new

  directiveAdded :undoc-members: option to the js:autoclass directive to provide a way to document the class members without docstrings.

• new

  directiveAdded :private-members: option to the js:autoclass directive to provide a way to document the private class members.

• new

  configurationAdded js_class_options global configuration value which contains a list of class directive boolean option activated by default.

  js_class_options=['members', 'undoc-members']
  

0.1.0

3 June 2017

• new

  configurationAdded js_source global configuration value which contains the path to the Javascript source code to parse.

• new

  javascript-parserAdded champollion.parser to parse Javascript source code.

• new

  Added champollion.viewcode to provide html source code linked to each API documentation generated.

• new

  directiveAdded AutoDataDirective directive to generate the documentation from a data id representing a variable parsed within the Javascript source code.

• new

  directiveAdded AutoFunctionDirective directive to generate the documentation from a function id representing a function parsed within the Javascript source code.

• new

  directiveAdded AutoClassDirective directive to generate the documentation from a class id representing a class parsed within the Javascript source code.

• new

  directiveAdded AutoMethodDirective directive to generate the documentation from a method id representing a class method parsed within the Javascript source code.

• new

  directiveAdded AutoAttributeDirective directive to generate the documentation from an attribute id representing a class attribute parsed within the Javascript source code.

• new

  documentationAdded installation documentation.

Glossary

Directive

A directive is a extension mechanism for reStructuredText used by Sphinx to provide a generic block of explicit markup.

See also

http://www.sphinx-doc.org/en/stable/rest.html#directives

Javascript

Programming language specified in the ECAMScript language specification.

See also

http://www.w3schools.com/js/

reStructuredText

reStructuredText is a markup language for textual data that uses simple and intuitive constructs to indicate the structure of a document.

See also

http://www.sphinx-doc.org/en/stable/rest.html

Sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

See also

www.sphinx-doc.org/

Virtualenv

A tool to create isolated Python environments.

See also

https://virtualenv.pypa.io/en/latest/

Indices and tables

• Index
• Module Index
• Search Page