Opened 18 months ago

Last modified 18 months ago

#25909 new enhancement

Optionally compile the documentation to jupyter notebooks

Reported by: nthiery Owned by:
Priority: major Milestone: sage-8.4
Component: documentation Keywords:
Cc: tmonteil Merged in:
Authors: Reviewers:
Report Upstream: N/A Work issues:
Branch: u/nthiery/optionally_compile_the_documentation_to_jupyter_notebooks (Commits) Commit: cf6da1aeeb8755aaefd5244fdff451c9d4bbe095
Dependencies: Stopgaps:

Description (last modified by nthiery)

We are regularly asked by users to provide our documentation in the form of Jupyter notebooks. The attached branch enables is an experimental step in this direction, enabling to build our Sphinx documentation as a collection of cross-linking notebooks with:

sage -pip install sphinxcontrib-jupyter make ipynb

This uses the following Sphinx plug-in:

which does a much better job than rst2ipynb (in particular it supports crosslinks etc.)

Note that there is still some unavoidadble degrading in the process, given that RST documentation page have intrinsically a tree structure while notebooks are intrinsically linear. Typically nested code blocks within lists or notes are not rendered perfectly.

Future steps:

  • [ ] Try the branch and check that it actually works
  • [ ] Check the output documentation to evaluate how much we are affected by the degrading
  • [ ] Document ipynb as build rule and docbuild target
  • [ ] Build and publish the notebooks on Sage's web page / binder
  • [ ] Build the notebooks by default?
  • [ ] Add links to the jupyter notebooks from the HTML documentation and/or from the Jupyter Help menu?

Change History (4)

comment:1 Changed 18 months ago by nthiery

  • Branch set to u/nthiery/optionally_compile_the_documentation_to_jupyter_notebooks

comment:2 Changed 18 months ago by nthiery

  • Commit set to cf6da1aeeb8755aaefd5244fdff451c9d4bbe095
  • Description modified (diff)

New commits:

cf6da1aCompilation of the documentation into jupyter notebooks (proof of concept implementation)

comment:3 Changed 18 months ago by nthiery

  • Description modified (diff)

comment:4 Changed 18 months ago by tmonteil

  • Cc tmonteil added
Note: See TracTickets for help on using tickets.