adding markdown cell for Watermark

[reshamas]

Add an explicit markdown cell for "Watermark".
This is for the Jupyter Style Guide.

#DataUmbrellaPyMCSprint

[reshamas]

@OriolAbril
I updated the instructions to include an explicit markdown cell.

I missed this in the divergence notebook PR:
https://github.com/pymc-devs/pymc-examples/blob/main/examples/diagnostics_and_criticism/Diagnosing_biased_Inference_with_Divergences.ipynb

and the other PRs I have worked on.

[OriolAbril]

I updated the instructions to include an explicit markdown cell.

Thanks

[OriolAbril]

I think the text should also be updated otherwise it doesn't really match anymore. How about something like this?

Suggested change

	## 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
	Once you're finished with your NB, add a a final code cell with [the watermark package](https://github.com/rasbt/watermark) preceded by a markdown cell with the section title:

Then move the

This will automatically print the versions of Python and the packages you used to run the NB -- reproducibility rocks!
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.

part after the code cell and remove the

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.

[reshamas]

@OriolAbril
I cleaned up the text in the Watermark section. I had found it confusing before because it referred to "last cell", but it's not really because of the footer. I broke it down into these:

• What is watermark?
• how to install it?
• add markdown, add code cell
• example code

[OriolAbril]

Thanks!

We should probably also add a page "About pymc-examples" in the "In-depth explanations" section with all the background on why we do each of the things, the mysy-ipynb duplication, the pre-commit checks (like forbidding internal links or links to other pyhton docs to be urls)... but it is hard to find time for this

[OriolAbril]

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.

[reshamas]

@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.

[OriolAbril]

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.

[OriolAbril]

approving but not merging yet as I am not sure what is going on with readthedocs

[reshamas]

approving but not merging yet as I am not sure what is going on with readthedocs

Is this related to the ads, or another issue with readthedocs?

[OriolAbril]

I was worried about the failing readthedocs check. I didn't think it was related to the adds though, now from slack discussions it looks like an obscure jax issue. both the readthedocs and the jax CI job have been failing since the last release so I will merge but as the job is failing, the website won't update until we fix that