Skip to content

Generate rich representations for docstrings

License

Notifications You must be signed in to change notification settings

spyder-ide/docrepr

Repository files navigation

Docrepr

Docrepr renders Python docstrings to HTML with Sphinx. It can generate rich and plain representations of docstrings, alongside additional metadata about the object to which the docstring belongs. It is based on the sphinxify module developed by Tim Dumol for the Sage Notebook and the utils.help module developed by Carlos Cordoba for the Spyder IDE. See spyder-ide/docrepr#20 for the full history.

Rationale

For more on the motivation and design behind Docrepr, see this presentation by Carlos Cordoba at SciPy 2015:

Towards a Better Documentation System for Scientific Python | SciPy 2015 | Carlos Cordoba

Details

The module renders a dictionary as returned by IPython oinspect module into a full HTML page (with all assets) from an object's docstring, by using the rich_repr function of its sphinxify submodule.

Example of use

import webbrowser

import numpy as np
from IPython.core.oinspect import Inspector   # oinfo generator

import docrepr                                # Set module options
from docrepr import sphinxify                 # html generator

oinfo = Inspector().info(np.sin)
oinfo['name'] = 'sin'
url = sphinxify.rich_repr(oinfo)

webbrowser.open_new_tab(url)

License

This project is distributed under the under the terms of the BSD 3-Clause License.