Skip to content

adding markdown cell for Watermark #6051

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

Merged
merged 8 commits into from
Aug 17, 2022
Merged

adding markdown cell for Watermark #6051

Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d9a6639
adding markdown cell for Watermark
reshamas Aug 15, 2022
8143e6f
clean up watermark section
reshamas Aug 16, 2022
b674f0e
show Markdown cell right above code cell
reshamas Aug 16, 2022
cb20b4d
remove flags explanation
reshamas Aug 16, 2022
fcb7f9a
solving precommit error
reshamas Aug 16, 2022
73ec7cf
clean up watermark section
reshamas Aug 16, 2022
29d5bbf
last code cell
reshamas Aug 17, 2022
4f0795f
Merge branch 'main' of github.com:pymc-devs/pymc into jupyter_watermark
reshamas Aug 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions docs/source/contributing/jupyter_style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -488,19 +488,24 @@ extra_bibtex_id_2
```

## Watermark
Once you're finished with your NB, add a very last cell with [the watermark package](https://github.com/rasbt/watermark). This will automatically print the versions of Python and the packages you used to run the NB -- reproducibility rocks! Here is some example code. Note that the `-p` argument may not be necessary (or it may need to have different libraries as input), but all the other arguments must be present.

[`watermark`](https://github.com/rasbt/watermark) is a library which automatically prints the versions of Python and the packages you used to run the NB -- reproducibility rocks!

This library should be in your virtual environment if you installed our `requirements-dev.txt`. Otherwise, run `pip install watermark`.

First, add a Markdown cell with the `## Watermark` title only so it appears in the table of contents. This is the second to last section, above the epilogue/footer. Then, add a code cell to print the versions of Python and packages used in the notebook.
Copy link
Member

@OriolAbril OriolAbril Aug 17, 2022

Choose a reason for hiding this comment

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

I find the "second to last section" description confusing. On the raw notebook, this is the last section/heading, the page_footer thing is only a markdown cell without heading. On the rendered docs, the page_footer is substituted by some content and it adds 2 headings, so in the page toc that appears on the website the Watermark is generally the 3rd to last heading.

I also would not mind if the watermark/references/author sections are swapped but yes, ideally they would appear in the order listed here in the style guide.

There is one piece of info that needs to be added though. IMO, what is key here is that the watermark is the last code cell in the notebook which is no longer mentioned.

Copy link
Member Author

@reshamas reshamas Aug 17, 2022

Choose a reason for hiding this comment

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

@OriolAbril
I added in "last code cell".

For my personal notebooks coding, I add the watermark cell at the top, after my imports so I can see in the beginning exactly what versions of the library I am using or need to use.

I am not sure why we need to specify "last code cell", though it's easy enough to add, and I added that in.

Copy link
Member

@OriolAbril OriolAbril Aug 17, 2022

Choose a reason for hiding this comment

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

That is something that should be documented in that "about pymc examples" page as we did discuss it during GSoD and agreed on putting it at the end like authors, references and citation advise.

The example notebooks are first and foremost documentation for pymc. Each of them has some authors and has potentially been adapted from a blog post even, but they are now part of the documentation. We believe it is important to recognize the specific authors but it is also information that has no relevance as documentation to a user trying to do model averaging.

The examples are also under a different versioning scheme than the rest of the documentation. That means that whatever version you are reading the API docs of, when you click on example gallery or on a text link that points to a notebook you will always get to latest slug. Notebooks will most commonly not be executed with the version you are using but they will still be valid and useful documentation; execptuating major versions, the API doesn't change that fast. Theferore, the fact that a notebook runs on 4.0.2 does not mean that the notebook is not valid to you because you use 4.1.4 (otherwise 95% of the docs would be permanently useless). The watermark is relevant only when things don't work to see which are the versions that work, try a different snapshot to see if it has been executed with a version closer to yours and that code works... and so we decided to put it at the bottom to avoid having it distract from the actual content.


The `p` flag is optional (or it may need to have different libraries as input), but should be added if Aesara or xarray are not imported explicitly. This will also be checked by `pre-commit` (because we all forget to do things sometimes 😳).

```markdown
## Watermark
```

```python
%load_ext watermark
%watermark -n -u -v -iv -w -p aesara,aeppl,xarray
```

This second to last code cell should be preceded by a markdown cell with the `## Watermark` title only so it appears in the table of contents.

`watermark` should be in your virtual environment if you installed our `requirements-dev.txt`.
Otherwise, just run `pip install watermark`.
The `p` flag is optional but should be added if Aesara or xarray are not imported explicitly.
This will also be checked by `pre-commit` (because we all forget to do things sometimes 😳).

## Epilogue
The last cell in the notebooks should be a markdown cell with exactly the following content:
Expand All @@ -515,5 +520,4 @@ update the path to page footer for the include to work.

---

You're all set now 🎉 You can push your changes, open a pull request, and, once it's merged, rest with the feeling of a job well done 👏
Thanks a lot for your contribution to open-source, we really appreciate it!
You're all set now 🎉. You can push your changes, open a pull request, and, once it's merged, rest with the feeling of a job well done 👏. Thanks a lot for your contribution to open-source, we really appreciate it!