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.

Sign up for GitHub

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

Jump to bottom

fixing jupytext markdown inconsistencies #288

Merged
merged 2 commits into from
Sep 2, 2019
Merged

fixing jupytext markdown inconsistencies #288

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
78b0e79
fixing jupytext markdown inconsistencies
choldgraf Sep 2, 2019
f85078d
making header info pass through for markdown files
choldgraf Sep 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
19 changes: 19 additions & 0 deletions jupyter_book/book_template/content/features/markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,18 @@
---
jupyter:
jupytext:
formats: md
text_representation:
extension: .md
format_name: markdown
format_version: '1.1'
jupytext_version: 1.2.1
kernelspec:
display_name: Python 3
language: python
name: python3
---

# Creating book content
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe changing this file is not necessary.

And the changes I see below (with Markdown comments surrounding the python code cells) raise an interesting question: should Python code blocks in the Markdown file always appear as executable code cells? As you noticed, these Markdown comments allow to preserve Jupyter's Markdown cells whatever there content is.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, I needed to change the file so that I could use the right sidebar popout, which Jupyter Book can only use with notebooks instead of markdown files, this is why I added the jupytext header. I'll put my thoughts about choosing markdown syntax in the issue so that we don't lose the conversation when this is merged!


The two kinds of files that contain course content are:
Expand All @@ -10,13 +25,15 @@ Each are contained in the `content/` folder and referenced from `_data/toc.yml`.
If the file is markdown, it will be copied over with front-matter YAML added so
that Jekyll can parse it.

<!-- #region -->
```python
print("Python (and any language-specific) code still works as expected")
```

```
As does non-language code.
```
<!-- #endregion -->

## Page navigation Table of Contents

Expand Down Expand Up @@ -45,13 +62,15 @@ P(A_1 \cup A_2 \cup A_3) ~ = ~ P(B \cup A_3) &= ~ P(B) + P(A_3) - P(BA_3) \\

And here is the code that was used to generate it:

<!-- #region -->
```python
\begin{align*}
P(A_1 \cup A_2 \cup A_3) ~ = ~ P(B \cup A_3) &= ~ P(B) + P(A_3) - P(BA_3) \\
&= ~ P(A_1) + P(A_2) - P(A_1A_2) + P(A_3) - P(A_1A_3 \cup A_2A_3)\\
&= ~ \sum_{i=1}^3 P(A_i) - \mathop{\sum \sum}_{1 \le i < j \le 3} P(A_iA_j) + P(A_1A_2A_3)
\end{align*}
```
<!-- #endregion -->

<!-- #region {"tags": ["popout"]} -->
**Note**: If you print your page (using the print button), then mathematics may not show
Expand Down
26 changes: 23 additions & 3 deletions jupyter_book/page.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@
from nbconvert.exporters import HTMLExporter
from nbconvert.writers import FilesWriter
import jupytext as jpt
import nbformat as nbf
from ruamel.yaml import YAML

from .utils import _clean_markdown_cells
from .utils import _clean_markdown_cells, _split_yaml
from .run import run_ntbk


Expand Down Expand Up @@ -35,8 +37,26 @@ def build_page(path_ntbk, path_html_output, path_media_output=None, execute=Fals

########################################
# Load in the notebook
notebook_name = op.splitext(op.basename(path_ntbk))[0]
ntbk = jpt.read(path_ntbk)
notebook_name, suff = op.splitext(op.basename(path_ntbk))

if suff in ['.md', '.markdown']:
# If it's a markdown file, we need to check whether it's a jupytext format
with open(path_ntbk, 'r') as ff:
lines = ff.readlines()
yaml, content = _split_yaml(lines)
yaml = YAML().load(''.join(yaml))

if (yaml is not None) and yaml.get('jupyter', {}).get('jupytext'):
# If we have jupytext metadata, then use it to read the markdown file
ntbk = jpt.reads(''.join(lines), 'md')
else:
# Otherwise, create an empty notebook and add all of the file contents as a markdown file
ntbk = nbf.v4.new_notebook()
ntbk['cells'].append(nbf.v4.new_markdown_cell(source=''.join(content)))
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi Chris, yes sure, at least this way we're going to fix the rendering of the Jupyter Book book itself. I think this is good enough for a quick fix, and as you suggest we will follow-up on this.

else:
# If it's not markdown, we assume it's either ipynb or a jupytext format
ntbk = jpt.read(path_ntbk)

if _is_jupytext_file(ntbk):
execute = True

Expand Down