Skip to content

Better RTD implementation of examples/documentation #32

Closed
@lukelbd

Description

@lukelbd

Currently, contributors cannot add examples. I generate examples from a big ipython notebook and convert them to RST with a shell script that calls nbconvert and does some regex magic to repair RST-style Sphinx module links embedded in the Markdown notebook cells (e.g. by default, nbconvert turns `~proplot.subplots.Figure` into ``~proplot.subplots.Figure``). This workflow also requires that every cell has already been executed, but committing cells with executed output is bad practice IMO -- ProPlot currently does not track or push cell output, thanks to nbstripout commands I've added to .git/info/attributes (see nbstripout for details).

In the near future, I need to commit the example notebook, use nbsphinx to automatically run each cell instead of running the cells manually myself, and configure nbsphinx with a formal nbconvert template/filter that repairs the links.

Alternatively, I may fork nbsphinx and implement this manually. Then I could add both my fork of sphinx-automodapi and nbsphinx as submodules inside proplot.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions