Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better RTD implementation of examples/documentation #32

Closed
lukelbd opened this issue Sep 5, 2019 · 1 comment
Closed

Better RTD implementation of examples/documentation #32

lukelbd opened this issue Sep 5, 2019 · 1 comment

Comments

@lukelbd
Copy link
Collaborator

lukelbd commented Sep 5, 2019

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.

@lukelbd lukelbd changed the title Better implementation of examples/documentation Better RTD implementation of examples/documentation Sep 15, 2019
@lukelbd
Copy link
Collaborator Author

lukelbd commented Nov 28, 2019

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
Projects
None yet
Development

No branches or pull requests

1 participant