Sustainability of the ipynb/nbformat Document Format

Special Topics
5

I guess a concrete next step of this discussion would be a Big Ol’ JEP that proposed a roadmap for describing the motivation, work required, etc. before we even had a chance at

A straw man:

A new, top-level Jupyter org, e.g. jupyter-spec tasked with owning/publishing versioned machine- and human-readable specifications without reference implementations…

jupyter-specs        # comes from... 
  content/           # notebook
  environment/       # repo2docker
  notebook/          # nbformat
  kernel-messages/   # jupyter_client
  kernelspec/        # jupyter_client?
  markdown/          # ???
  pdf/               # ???
  well-known/        # notebook? nbconvert? repo2docker?
  widgets/           # ipywidgets

The rough structure of each:

(README|LICENSE|CONTRIBUTING|CODE_OF_CONDUCT|ROADMAP).md  # the usual
Makefile
.github/(templates|actions)
specifications-proposed/
specifications/
implementations/

Where each (specification|proposal) directory contained whatever is needed to:

  • common metadata (version, points of contact, etc)
  • formally describe the specification in a machine readable format (to the extent possible)…
    • JSON Schema
    • EBNF
  • … augmented with narrative-style docs
    • notebooks
  • … from which, generate human-readable, cross-linkable HTML documentation
    • probably a sphinx pipeline
  • … as well as a chosen spec target, e.g. IETF, W3C, ISO, whatever makes sense
  • a conformance suite of good (and pathological!) examples in non-language-specific formats

While each implementation would provide:

  • common metadata (repo, license)
  • the specifications supported
    • to what level, perhaps
  • links to conformance test results…
    • probably xunit
  • …or, if open source, or in some other way excitable from CI (e.g. SaaS), a way to run the suite

Thoughts?