Conversation
|
|
||
| with this line so that Sphinx can parse Markdown files: | ||
| ```python | ||
| extensions = ['myst_parser'] |
There was a problem hiding this comment.
Not a strong opinion, but the content of conf.py created by sphinx-quickstart (8.2.3) use single quotes, so it's a little weird to change this here.
| ``` | ||
|
|
||
| 2. In the file `conf.py` modify "extensions" and add 3 lines: | ||
| 2. In the file `conf.py` modify "extensions" and add the `autodoc2_packages` with `"multiply.py"`: |
There was a problem hiding this comment.
| 2. In the file `conf.py` modify "extensions" and add the `autodoc2_packages` with `"multiply.py"`: | |
| 2. In the file `conf.py` add `autodoc2` to the "extensions", and add the list `autodoc2_packages` which will mention `"multiply.py"`: |
|
|
||
| `````{exercise} Sphinx-4: Writing Sphinx content with Jupyter | ||
|
|
||
| 1. Create a text-based notebook files `flower.md` in the same directory as the `index.rst` file. This file will be converted to a Jupyter notebook by the `myst_nb` Sphinx extension and then executed by Jupyter. Fill the file with the following content: |
There was a problem hiding this comment.
| 1. Create a text-based notebook files `flower.md` in the same directory as the `index.rst` file. This file will be converted to a Jupyter notebook by the `myst_nb` Sphinx extension and then executed by Jupyter. Fill the file with the following content: | |
| 1. For simplicity, create a text-based notebook files `flower.md` in the same directory as the `index.rst` file. This file will be converted to a Jupyter notebook by the `myst_nb` Sphinx extension and then executed by Jupyter. Fill the file with the following content: |
| ``` | ||
| ```` | ||
|
|
||
| 2. In the file `conf.py` modify `extensions` to remove `"myst_parser"` and add `"myst_nb"` (you will get an error if you include both): |
There was a problem hiding this comment.
| 2. In the file `conf.py` modify `extensions` to remove `"myst_parser"` and add `"myst_nb"` (you will get an error if you include both): | |
| 2. In the file `conf.py` modify `extensions` to remove `"myst_parser"` and add `"myst_nb"` ([you will get an error if you include both](https://myst-nb.readthedocs.io/en/latest/quickstart.html)): |
| ax.plot(theta, np.full(len(theta), -1)); | ||
| ``` | ||
| ```` | ||
|
|
There was a problem hiding this comment.
| Note that there needs to be a title in the notebook (a heading starting with a single `#`), that will be used as an entry and link in the table of content. |
|
|
||
| 4. Re-build the documentation and check the "Flower" section. | ||
|
|
||
| 5. (Optional) As an alternative to including a text-based notebook with an `.md` file in your documentation, you can add a `.ipynb` files saved from Jupyter notebook or Jupyter lab. Just make sure to 1) start the notebook with a markdown cell with a `# Title` so it can be included in the table of contents 2) save the notebook in the same directory as `index.rst` and 3) list it in the toctree in `index.rst`. |
There was a problem hiding this comment.
I have tested it, there is no need to save the notebook in the same directory as index.rst, as long as the path is correctly specified.
Also, I think that jupyter notebooks as ipynb's may still be more appealing and direct than the text-based alternative (although, I love the text-based ones), and the fact that ipynb stores by default the results might be used, as discussed previously elsewhere, for validation.
So I would not present that as a secondary idea, but as an idea as relevant as the first one.
| 5. (Optional) As an alternative to including a text-based notebook with an `.md` file in your documentation, you can add a `.ipynb` files saved from Jupyter notebook or Jupyter lab. Just make sure to 1) start the notebook with a markdown cell with a `# Title` so it can be included in the table of contents 2) save the notebook in the same directory as `index.rst` and 3) list it in the toctree in `index.rst`. | |
| 5. You can add a `.ipynb` files saved from Jupyter notebook or Jupyter lab. Just make sure to list it in the toctree in `index.rst` with the correct path. | |
| If you have problems, consider cleaning manually the `jupyter_execute` directory. |
|
Please consider my suggestions, but do not feel obliged to accept the ones that look mostly opinion-based. One could add a couple of sentences about the advantages and disadvantages of using text-based notebook formats, but maybe this can become its own issue that we can postpone for the moment. |
2 participants
This PR also adds some cleanups to the other Sphinx exercises