Skip to content

Better RTD implementation of examples/documentation #32

Closed

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.

Activity

  1. changed the title [-]Better implementation of examples/documentation[/-] [+]Better RTD implementation of examples/documentation[/+] on Sep 15, 2019
  2. lukelbd commented on Nov 28, 2019

    @lukelbd
    CollaboratorAuthor

    Closed by #47. In the end I didn't fork nbsphinx -- I just use raw "RST" cells instead of markdown cells for the example descriptions, which permits sprinkling the :py:obj Sphinx links throughout the examples.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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