Skip to content

📚👌‼️: Improve documentation and usability#405

Merged
chrisjsewell merged 5 commits into
masterfrom
new-docs
Apr 27, 2022
Merged

📚👌‼️: Improve documentation and usability#405
chrisjsewell merged 5 commits into
masterfrom
new-docs

Conversation

@chrisjsewell
Copy link
Copy Markdown
Member

This PR completely restructures the documentation and makes a number of key usability improvements:

  1. Simplified top-matter for text-based notebooks

The previous usage of a jupytext configuration will still work, e.g.

---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: '0.13'
    jupytext_version: 1.13.8
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

but now the following can also signify a text-based notebook:

---
file_format: mystnb
kernelspec:
  name: python3
---

Note display_name is no longer required to be specified, since it is added as the name, if missing.

  1. The cell metadata key render is replaced with mystnb, to make it consistent with the notebook metadata key. For old notebooks using render, this will still be read and issue a deprecation warning

  2. The mystnb-quickstart CLI command has been added, to create a template Sphinx + MyST-NB project

@chrisjsewell chrisjsewell changed the title 📚👌‼️: Improve usability 📚👌‼️: Improve documentation and usability Apr 27, 2022
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 27, 2022

Codecov Report

Merging #405 (8360c65) into master (ba22f95) will increase coverage by 0.30%.
The diff coverage is 85.71%.

@@            Coverage Diff             @@
##           master     #405      +/-   ##
==========================================
+ Coverage   80.13%   80.44%   +0.30%     
==========================================
  Files          20       21       +1     
  Lines        2059     2132      +73     
==========================================
+ Hits         1650     1715      +65     
- Misses        409      417       +8     
Flag Coverage Δ
pytests 80.44% <85.71%> (+0.30%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files Coverage Δ
myst_nb/glue/directives.py 69.85% <0.00%> (ø)
myst_nb/glue/roles.py 56.47% <0.00%> (ø)
myst_nb/glue/utils.py 64.86% <0.00%> (ø)
myst_nb/docutils_.py 77.94% <66.66%> (+1.66%) ⬆️
myst_nb/core/config.py 77.50% <81.81%> (-2.28%) ⬇️
myst_nb/sphinx_.py 89.36% <83.33%> (-0.47%) ⬇️
myst_nb/core/render.py 83.28% <90.00%> (ø)
myst_nb/cli.py 92.45% <92.45%> (ø)
myst_nb/core/preprocess.py 88.63% <100.00%> (+0.54%) ⬆️
myst_nb/core/read.py 80.11% <100.00%> (+0.46%) ⬆️
... and 1 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ba22f95...8360c65. Read the comment docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant