search

UBC-DSCI / introduction-to-datascience-python

Open Source Textbook for DSCI100: Introduction to Data Science in Python
https://python.datasciencebook.ca
Other
10 stars 8 forks source link

PDF non-running code blocks either aren't formatted well or do have to run in the bkg #342

Open trevorcampbell opened 8 months ago

trevorcampbell commented 8 months ago

Throughout the book in a few places we need to make a code block that looks like it's running but actually it does nothing and some hidden code runs instead. There are a few examples of this in the reading chapter.

We used to use a pattern like:

    ```python
    code.that_is_shown_but_doesnt_run()
```text
fake_output_of_code
   ```{code-cell} ipython3
   :tags: ["remove-input"]
   hidden_code.that_actually_runs()

But in the PDF build, `python` and `text` blocks don't look like code /output (even though in the HTML build they do). The major issue is that the `.md` files get processed to `.ipynb` files, which distinguish between markdown and code cells -- the `python` and `text` blocks are processed as markdown, while `code-cell` blocks are processed as code.

The right strategy here is probably to somehow edit the pdf style of python/text blocks in myst/sphinx/jbook/???. But I really couldn't figure out how to do it (or even where to do it...).

The strategy I'm taking now in PR #341 is to actually use code blocks that run but discard their output, and fake the output as an actual code cell output using a print (eek....).
```{code-cell} ipython3
:tags: ["remove-output"]
code.that_is_shown_but_doesnt_run()
```
```{code-cell} ipython3
:tags: ["remove-input"]
print("fake_output_of_code")
   ```{code-cell} ipython3
   :tags: ["remove-input"]
   hidden_code.that_actually_runs()

This looks the same in HTML but fixes the PDF render.

BUT it is really not great, because code that was previously in `python` tags that shouldn't run is actually running...so we need to handle the broken results of these now. 

I'll leave this issue here just to say this is currently not fantastic and we should try to get back to the non-running `python`/`text` tag version of things at some point.