From 33b2bbf873c0c582cdac0aaed34a5e444ad21f68 Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Wed, 24 Nov 2021 20:08:27 +0200 Subject: [PATCH 1/6] minor fixes to docs --- docs/source/conf.py | 2 -- docs/source/contributing/jupyter_style.md | 24 ++++++++++++++++++----- 2 files changed, 19 insertions(+), 7 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8ab978a6b3..12397cf01c 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,11 +44,9 @@ "IPython.sphinxext.ipython_console_highlighting", "IPython.sphinxext.ipython_directive", "sphinx.ext.autosectionlabel", - "sphinx.ext.napoleon", "myst_nb", "sphinx_design", "notfound.extension", - "sphinx_design", "sphinx_copybutton", ] diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 4deb659691..e53f9332d5 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -29,10 +29,14 @@ the repository where the notebook is in (pymc or pymc-examples). * When using non meaningful names such as single letters, add bullet points with a 1-2 sentence description of each variable below the equation where they are first introduced. -## Post directive -The first cell of all example notebooks should have a level 1 markdown title (that is a title with a single `#`) followed by the post directive. The syntax of the post directive is as follows: +## First cell +The first cell of all example notebooks should have a MyST target, a level 1 markdown title (that is a title with a single `#`) followed by the post directive. +The syntax is as follows: ``` +(notebook_id)= +# Notebook Title + :::{post} Aug 31, 2021 :tags: tag1, tag2, tags can have spaces, tag4 :category: level @@ -42,15 +46,22 @@ The first cell of all example notebooks should have a level 1 markdown title (th The date should correspond to the latest update/execution date, at least roughly (it's not a problem if the date is a few days off due to the review process before merging the PR). This will allow users to see which notebooks have been updated lately and will help the PyMC team make sure no notebook is left outdated for too long. -Tags can be anything, but we ask you to try to use [existing tags](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples) to avoid the tag list from getting too long. Each notebook should -have a single category indicating the level of the notebook. Choose a category from [existing categories](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples#categories). +The [MyST target](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing) +is important to ease referencing and linking notebooks between them. + +Tags can be anything, but we ask you to try to use [existing tags](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples) +to avoid the tag list from getting too long. + +Each notebook should have a single category indicating the level of the notebook. +Choose a category from [existing categories](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples#categories). Authors should list people who authored, adapted or updated the notebook. See {ref}`jupyter_authors` for more details. ## Code preamble -In a cell just below the cell where you imported matplotlib (usually the first one), set the ArviZ style to darkgrid (this has to be in another cell than the MPL import because of the way MPL sets its defaults): +In a cell just below the cell where you imported matplotlib and/or ArviZ (usually the first one), +set the ArviZ style to darkgrid (this has to be in another cell than the matplotlib import because of the way matplotlib sets its defaults): ```python RANDOM_SEED = 8927 @@ -122,6 +133,7 @@ and `` should preferably be month and year. authored : for notebooks created specifically for pymc-examples + adapted : for notebooks adapted from other sources such as books or blogposts. It will therefore follow a different structure than the example above @@ -130,9 +142,11 @@ adapted ```markdown Adapted from Alice's [blogpost](blog.alice.com) by Bob and Carol on ... ``` + re-executed : for notebooks re-executed with a newer PyMC version without significant changes to the code. It can also mention the PyMC version used to run the notebook. + updated : for notebooks that have not only been re-executed but have also had significant updates to their content (either code, explanations or both). From e15d535ea148b0e6d63bc7dd3a1a2be1958c40af Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Wed, 24 Nov 2021 20:15:53 +0200 Subject: [PATCH 2/6] try fixing pymc-lab logo --- docs/source/conf.py | 2 +- docs/source/index.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 12397cf01c..d4f5dcdf37 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -230,7 +230,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ["_static", "nb_tutorials/_images", "nb_examples/_images"] +html_static_path = ["../logos"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/source/index.md b/docs/source/index.md index 957fa089e8..1379feb52b 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -19,6 +19,7 @@ Probabilistic Programming in Python :::{button-ref} learning :color: primary :ref-type: ref +:class: btn-lg Get started! ::: @@ -94,6 +95,7 @@ PyMC is a non-profit project under NumFOCUS umbrella. If you value PyMC and want ::::{div} sd-d-flex-row sd-align-major-center :::{button-link} https://numfocus.org/donate-to-pymc3 :color: secondary +:class: btn-lg Donate @@ -114,7 +116,7 @@ Donate ::: :::{grid-item-card} -:img-background: https://github.com/pymc-devs/pymc/raw/main/docs/pymc-labs-logo.png +:img-background: logos/sponsors/pymc-labs.png :link: https://www.pymc-labs.io/ :shadow: none ::: From d45aa153b05705586a2dead06c4f4c7d4a76bc1a Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Wed, 24 Nov 2021 20:23:30 +0200 Subject: [PATCH 3/6] set first cell language to markdown --- docs/source/contributing/jupyter_style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index e53f9332d5..9c215dda22 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -33,7 +33,7 @@ the repository where the notebook is in (pymc or pymc-examples). The first cell of all example notebooks should have a MyST target, a level 1 markdown title (that is a title with a single `#`) followed by the post directive. The syntax is as follows: -``` +```markdown (notebook_id)= # Notebook Title From f586504bc4d5900347c96bcc03a11cbcd2a9dbff Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Thu, 25 Nov 2021 05:05:04 +0200 Subject: [PATCH 4/6] make homepage buttons larger --- docs/source/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index 1379feb52b..db246a27cf 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -19,7 +19,7 @@ Probabilistic Programming in Python :::{button-ref} learning :color: primary :ref-type: ref -:class: btn-lg +:class: sd-fs-2 sd-px-5 Get started! ::: @@ -95,7 +95,7 @@ PyMC is a non-profit project under NumFOCUS umbrella. If you value PyMC and want ::::{div} sd-d-flex-row sd-align-major-center :::{button-link} https://numfocus.org/donate-to-pymc3 :color: secondary -:class: btn-lg +:class: sd-fs-2 sd-px-5 Donate From 2be6a76bd1c2f53eceb5cf6abedd1b43c960e200 Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Thu, 25 Nov 2021 05:19:16 +0200 Subject: [PATCH 5/6] fix sponsor images --- docs/source/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index db246a27cf..a1401acba9 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -110,13 +110,13 @@ Donate ::: :::{grid-item-card} -:img-background: https://www.numfocus.org/wp-content/uploads/2017/07/NumFocus_LRG.png +:img-background: _static/sponsors/numfocus.png :link: https://numfocus.org/ :shadow: none ::: :::{grid-item-card} -:img-background: logos/sponsors/pymc-labs.png +:img-background: _static/sponsors/pymc-labs.png :link: https://www.pymc-labs.io/ :shadow: none ::: From 1cf20b167776e8817323c8ecd405040a54c91318 Mon Sep 17 00:00:00 2001 From: Oriol Abril-Pla Date: Sat, 27 Nov 2021 04:19:14 +0100 Subject: [PATCH 6/6] Update docs/source/contributing/jupyter_style.md Co-authored-by: Martina Cantaro <6120897+martinacantaro@users.noreply.github.com> --- docs/source/contributing/jupyter_style.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/jupyter_style.md b/docs/source/contributing/jupyter_style.md index 9c215dda22..b3f6c34051 100644 --- a/docs/source/contributing/jupyter_style.md +++ b/docs/source/contributing/jupyter_style.md @@ -47,7 +47,7 @@ The syntax is as follows: The date should correspond to the latest update/execution date, at least roughly (it's not a problem if the date is a few days off due to the review process before merging the PR). This will allow users to see which notebooks have been updated lately and will help the PyMC team make sure no notebook is left outdated for too long. The [MyST target](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing) -is important to ease referencing and linking notebooks between them. +is important to ease referencing and linking notebooks between each other. Tags can be anything, but we ask you to try to use [existing tags](https://github.com/pymc-devs/pymc/wiki/Categories-and-Tags-for-PyMC-Examples) to avoid the tag list from getting too long.