✨♻️‼️ Rewrite myst-nb

.github/workflows/tests.yml

@@ -26,7 +26,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
         sphinx: [">=3,<4", ">=4,<5"]
         include:
           - os: windows-latest

.gitignore

@@ -130,9 +130,12 @@ dmypy.json
 .pyre/
 
 # Jupyter Cache
-docs/.jupyter_cache
+.jupyter_cache
 
 # OSX
 .DS_Store
 
 .vscode/
+
+todos.md
+_archive/

.pre-commit-config.yaml

@@ -42,17 +42,20 @@ repos:
     - id: flake8
       additional_dependencies: [flake8-bugbear==21.3.1]
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.910-1
-    hooks:
-    - id: mypy
-      args: [--config-file=setup.cfg]
-      additional_dependencies:
-      - myst-parser~=0.14.0
-      files: >
-        (?x)^(
-            myst_nb/parser.py|
-        )$
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: v0.910-1
+  #   hooks:
+  #   - id: mypy
+  #     args: [--config-file=setup.cfg]
+  #     additional_dependencies:
+  #     - importlib_metadata
+  #     - myst-parser~=0.16.1
+  #     - "sphinx~=4.3.2"
+  #     - types-PyYAML
+  #     files: >
+  #       (?x)^(
+  #           myst_nb/[^/]+.py|
+  #       )$
 
   # this is not used for now,
   # since it converts myst-nb to myst_nb and removes comments

MANIFEST.in

@@ -11,4 +11,4 @@ exclude codecov.yml
 include LICENSE
 include CHANGELOG.md
 include README.md
-include myst_nb/_static/mystnb.css
+include myst_nb/static/mystnb.css

docs/api/index.rst

@@ -3,16 +3,70 @@
 Python API
 ==========
 
-.. toctree::
-    :maxdepth: 2
+The parsing of a notebook consists of a number of stages, with each stage separated into a separate module:
 
-    nodes
-    render_outputs
+1. The configuration is set (from a file or CLI)
+2. The parser is called with an input string and source
+3. The parser reads the input string to a notebook node
+4. The notebook code outputs are potentially updated, via execution or from a cache
+5. The notebook is "pre-processed" in-place (e.g. to coalesce output streams and extract glue outputs)
+6. The notebook is converted to a Markdown-It tokens syntax tree
+7. The syntax tree is transformed to a docutils document AST (calling the renderer plugin)
+8. The docutils document is processed by docutils/sphinx, to create the desired output format(s)
 
-Miscellaneous
+Configuration
 -------------
 
-.. autoclass:: myst_nb.ansi_lexer.AnsiColorLexer
+.. autoclass:: myst_nb.configuration.NbParserConfig
+    :members:
+
+Parsers
+-------
+
+.. autoclass:: myst_nb.docutils_.Parser
+    :members:
+
+.. autoclass:: myst_nb.sphinx_.Parser
+    :members:
+
+Read
+----
+
+.. autoclass:: myst_nb.read.NbReader
+    :members:
+
+.. autofunction:: myst_nb.read.create_nb_reader
+
+.. autofunction:: myst_nb.read.is_myst_markdown_notebook
+
+.. autofunction:: myst_nb.read.read_myst_markdown_notebook
+
+Execute
+-------
+
+.. autoclass:: myst_nb.execute.ExecutionResult
+    :members:
+
+.. autofunction:: myst_nb.execute.execute_notebook
+
+Pre-process
+-----------
+
+.. autofunction:: myst_nb.preprocess.preprocess_notebook
+
+Render plugin
+-------------
+
+.. autoclass:: myst_nb.render.MimeData
+    :members:
+
+.. autoclass:: myst_nb.render.NbElementRenderer
+    :members:
+
+Lexers
+------
+
+.. autoclass:: myst_nb.lexers.AnsiColorLexer
     :members:
     :undoc-members:
     :show-inheritance: