Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📚👌‼️: Improve documentation and usability #405

Merged
merged 5 commits into from
Apr 27, 2022
Merged

Conversation

chrisjsewell
Copy link
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

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