how_to.md

About this book

How to use this book

Navigating tags

Each case is categorized by a collection of relevant tags. A specific tag's cases (such as 2D) can be navigated through the 🏷 Tags index.

Executing and editing code

Press the {fas}rocket button on the toolbar, then the {fas}play button to edit and run the code.

This might take a while to load after new releases of the book.

How to contribute

Converting Markdown files to Jupyter notebooks

All V&V cases are tracked as Markdown files in the {MyST}NB format, which allows us to use useful MyST directives and track the code in the same raw text file. You can run jupytext --sync on the .md MyST-NB file to convert it to a jupytext notebook. Running the same command will sync all changes between the files.

You can also download any case as a Jupyter notebook by clicking the {fas}download button on the toolbar and selecting the {fas}code .ipynb option.

Adding a case

1. Create a Jupyter notebook for editing the case.

2. Run jupytext --set-formats ipynb,myst on the .ipynb notebook file. This creates a "paired" Markdown file which we will be tracking on git.

3. Add the path to the case to the table of contents located at ./report/_toc.yml under the appropriate chapter.

   The files in the table of contents lack an extension. This is useful for testing since jupyter-book will prioritize `.ipynb` files over `.md` files when building the book.
   

You can build the book locally by running jupyter-book build ./report.

Coding Guidelines

TODO

Final Touches

1. Add category tags by using the {tags} directive below the case title as follows:

   ```{tаgs} tag1, tag2
   ```

2. Add "hide" tags to the code cells in the case where appropriate. Ideal visible outputs only contain figures.

3. Format the code using black on the notebook file as follows black notebook.ipynb.

   Jupyter notebook support for black can be installed with `pip install black[jupyter]`.