Provide an end-to-end prototype of delivering rich documentation in Jupyter clients

[bollwyvl]

elevator pitch

Provide a pip-installable lab|notebook|terminal|lite experience for discovering, browsing, and searching well-formed documentation.

motivation

While Jupyter clients provide a robust way to deliver many forms of local content to users, documentation (crucially of jupyter tools themselves) generally are only provided as links to externally-hosted sites.

design ideas

in the browser

• offer a Documentation link/tab in the in the lab|notebook launcher
• fetch a browseable list of known (and/or indexed) documentation sources
• offer indexed, faceted search of all documentation sources
• allow for users to curate their documentation library
  • offer a way to upload new files in supported formats
  • offer standards-based bookmarking and annotation

on the server

• define a new well-known location for documentation, e.g. ${PREFIX}/share/jupyter/documentation
• provide discovery and indexing of standard and widely-available on-disk formats
  • .ipynb
  • .epub
  • .pdf
  • .docset
• accept new user content in supported formats
  • leave hooks for more complex use cases
• serve raw documentation static assets

in the kernel

• provide a well-known comm target for kernels to advertise they (could) provide documentation in a above standard format
• for example, python can generate a site for a specific library with the stdlib pydoc

in the build

• when publishing this package, it would additionally offer a few dogfooding techniques
  • include by default a user guide for this software itself, in the form of an .epub
  • as an optional dependency, offer the js/python API documentation as .docsets
  • offer some notebook starting points
  • in the documentation site for this package, offer all of the above inside of an interactive kernel experience

prior art

• papyri
  • requires documentation to be re-built in novel intermediate formats
• ferenda
  • demonstrates a pipeline-based way to get to both an intermediate graph and various output formats
• web annotation data model
  • any other choice is probably going
• zeal
  • likely little to reuse directly, but probably some good patterns