From b2200af246bf46c7fe2d247a426d92f172ad9ac2 Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Tue, 4 Jan 2022 06:17:24 +0200 Subject: [PATCH 1/3] modify the layout --- _static/custom.css | 13 +++++ _templates/postcard.html | 21 ++------ _templates/postcard_categories.html | 64 +++++++++++++++++++++++ examples/blog.md | 2 +- examples/conf.py | 7 ++- examples/index.md | 79 ++++++++++++++++++++++++++--- 6 files changed, 157 insertions(+), 29 deletions(-) create mode 100644 _static/custom.css create mode 100644 _templates/postcard_categories.html diff --git a/_static/custom.css b/_static/custom.css new file mode 100644 index 000000000..1cc981de3 --- /dev/null +++ b/_static/custom.css @@ -0,0 +1,13 @@ +/* taken from sphinx-codeautolink examples */ +.sphinx-codeautolink-a{ + border-bottom-color: rgb(0, 0, 0); + border-bottom-style: dotted; + border-bottom-width: 1px; +} +.sphinx-codeautolink-a:hover{ + color: rgb(255, 139, 139); +} + +.bd-sidebar { + overflow-y: auto; +} diff --git a/_templates/postcard.html b/_templates/postcard.html index f7c3956e7..f6f38be22 100644 --- a/_templates/postcard.html +++ b/_templates/postcard.html @@ -1,30 +1,17 @@ {% if pagename in ablog %} - {% set fa = ablog.fontawesome %} {% set post = ablog[pagename] %} -

Notebook metadata

- {% endif %} diff --git a/_templates/postcard_categories.html b/_templates/postcard_categories.html new file mode 100644 index 000000000..0a13ecd50 --- /dev/null +++ b/_templates/postcard_categories.html @@ -0,0 +1,64 @@ +{%- macro pathtocategory(category) -%} + {% set path = "blog/category/" + category %} + {{ pathto(path) }} +{%- endmacro -%} + +{%- macro setcolorclass(active) -%} + {% if active %} + {{ "sd-text-success" }} + {% else %} + {{ "sd-text-muted" }} + {% endif %} +{%- endmacro -%} + + +{%- macro category_item(name, icon, active) -%} + + + + +{%- endmacro -%} + + + +{% set post = ablog[pagename] %} + + +

+ {{ gettext('Categories') }} +

+
+ + {% set i_bool = "intermediate" in post.category|map('string') %} + {% set b_bool = "beginner" in post.category|map('string') %} + {% set a_bool = "advanced" in post.category|map('string') %} +
+
+
+ {{ category_item("beginner", "fa-crow", b_bool) }} +
+
+ {{ category_item("intermediate", "fa-dove", i_bool) }} +
+
+ {{ category_item("advanced", "fa-dragon", a_bool) }} +
+
+
+ + +
+
+ {% set t_bool = "tutorial" in post.category|map('string') %} +
Tutorial
+ {% set h_bool = "how-to" in post.category|map('string') %} +
How-to
+
+ {% set e_bool = "explanation" in post.category|map('string') %} +
Explanation
+ {% set r_bool = "reference" in post.category|map('string') %} +
Reference
+
+
+ +
diff --git a/examples/blog.md b/examples/blog.md index 2e4e4ea1a..aa11c5034 100644 --- a/examples/blog.md +++ b/examples/blog.md @@ -1,3 +1,3 @@ -# Blog +# Recent updates diff --git a/examples/conf.py b/examples/conf.py index 9e85afecb..9398b1869 100644 --- a/examples/conf.py +++ b/examples/conf.py @@ -68,6 +68,7 @@ {"name": "Learning", "url": "https://docs.pymc.io/en/stable/learn.html"}, {"name": "API", "url": "https://docs.pymc.io/en/stable/api.html"}, ], + "page_sidebar_items": ["postcard", "page-toc", "edit-this-page"], } version = os.environ.get("READTHEDOCS_VERSION", "") version = version if "-" in version else "main" @@ -90,15 +91,13 @@ # 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"] +html_css_files = ["custom.css"] templates_path = ["../_templates"] -# Workaround to make the whole sidebar scrollable. See https://github.com/pydata/pydata-sphinx-theme/issues/500 -# ideally the tagcloud, categories and ads would be added from here in conf.py html_sidebars = { "**": [ # "sidebar-nav-bs.html", - "postcard.html", + "postcard_categories.html", "tagcloud.html", - "categories.html", "sidebar-ethical-ads.html", ], } diff --git a/examples/index.md b/examples/index.md index 46bf0e87d..a8142ffe5 100644 --- a/examples/index.md +++ b/examples/index.md @@ -1,14 +1,79 @@ # PyMC example gallery -This is a WIP website. +**Welcome to the PyMC example gallery!** -This homepage is temporarily empty while we format and categorize -all example notebooks as posts. You can see the tags and -categories on the left sidebar and reach the already updated notebooks -from there. All notebooks are rendered in the website though, you can access them -via the search bar. +The PyMC example gallery is a collection of Jupyter notebooks +about PyMC and its usage. These notebooks range can be tutorials, +case studies or in-depth explanations. +Some notebooks were originally blogposts, others were adapted from books +and some were written specifically for this example gallery. +This homepage explains the organization of the website and provides +some pointers on how to navigate it. + +The collection contains more than 90 notebooks. We are therefore unable +to ensure notebooks are updated and re-executed at the same pace we +publish PyMC releases. Consequently, PyMC has two documentation +websites: the versioned docs and the example gallery + +**Versioned docs** +We publish the versioned docs directly at `docs.pymc.io`. The only additions +to the url are the language and version of the documentation. + +The versioned docs are synced with PyMC releases and contain a handful of +guides about core functionality and the API documentation among other things. + +**Example gallery** +We publish the example gallery as a subproject of the versioned docs: `docs.pymc.io/projects/examples` +This means that the building process, language and version of the +example gallery are independent from the versioned docs. However, +the {ref}`search bar in the versioned docs ` searches +both the versioned docs and the example gallery at the same time +(but not the other way around). + +We will update the notebooks in the example gallery regularly +and publish the updates to the example gallery website with each commit. +We recommend using the example gallery as an unversioned living +resource, but we will also provide snapshots every few months for cases such as books +that need links to a stable resource. + +You can access the snapshots from the version menu at the bottom right of the page. +A version number in the `YYYY.0M.MICRO` format identifies the time the snapshot was published. + +--- + +Notebooks are treated as blogposts. The metadata of each notebook +describes its topics and type of content via tags and categories +and the last update date. We believe that tags and categories +ease and improve navigation (as opposed to a fixed topic division/hierarchy). +In addition, we also provide a list of recent updates and a search bar in the +navigation bar at the top of the page. + +:::{caution} +The website is still in construction. Thus, not all notebooks have been updated +to include all the relevant metadata. Those notebooks can only be reached +from the search bar +::: + +## Categories +Notebooks have at most two categories, one indicating the level of the +notebook and another indicating the type of content according to the +[diataxis framework](https://diataxis.fr/). The left sidebar +shows all 7 categories (3 levels + 4 types) at all times. You can click +there to reach the page listing all the notebooks in that category. +If a page has some categories in its metadata they are highlighted in green +in the category list. + +## Tags +Notebooks can have any number of tags. Each tag represents a specific topic +of potential interest to readers or a pymc object used within that notebook. + +The left sidebar shows all tags at all times. Like categories, they can be clicked +on to reach the page listing all notebooks that contain the tag. If a notebook +has tags in its metadata they are listed on the right sidebar after the {fas}`tags` icon. :::{toctree} -:maxdepth: 2 +:maxdepth: 1 +:hidden: + blog ::: From cb4159481762bb3b750d7b805dc1d1230ccd0f1b Mon Sep 17 00:00:00 2001 From: Oriol Abril-Pla Date: Tue, 4 Jan 2022 05:43:31 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Thomas Wiecki --- examples/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/examples/index.md b/examples/index.md index a8142ffe5..d35910721 100644 --- a/examples/index.md +++ b/examples/index.md @@ -3,9 +3,9 @@ **Welcome to the PyMC example gallery!** The PyMC example gallery is a collection of Jupyter notebooks -about PyMC and its usage. These notebooks range can be tutorials, +about PyMC and its usage. These notebooks can be tutorials, case studies or in-depth explanations. -Some notebooks were originally blogposts, others were adapted from books +Some notebooks were originally blog posts, others were adapted from books and some were written specifically for this example gallery. This homepage explains the organization of the website and provides some pointers on how to navigate it. @@ -23,7 +23,7 @@ The versioned docs are synced with PyMC releases and contain a handful of guides about core functionality and the API documentation among other things. **Example gallery** -We publish the example gallery as a subproject of the versioned docs: `docs.pymc.io/projects/examples` +We publish the example gallery as a sub-project of the versioned docs: `docs.pymc.io/projects/examples` This means that the building process, language and version of the example gallery are independent from the versioned docs. However, the {ref}`search bar in the versioned docs ` searches @@ -41,7 +41,7 @@ A version number in the `YYYY.0M.MICRO` format identifies the time the snapshot --- -Notebooks are treated as blogposts. The metadata of each notebook +Notebooks are treated as blog posts. The metadata of each notebook describes its topics and type of content via tags and categories and the last update date. We believe that tags and categories ease and improve navigation (as opposed to a fixed topic division/hierarchy). @@ -49,9 +49,9 @@ In addition, we also provide a list of recent updates and a search bar in the navigation bar at the top of the page. :::{caution} -The website is still in construction. Thus, not all notebooks have been updated +The website is still under construction. Thus, not all notebooks have been updated to include all the relevant metadata. Those notebooks can only be reached -from the search bar +from the search bar. ::: ## Categories From 0551708fc4f54c0f8d5212a34993a5eff0de5b5e Mon Sep 17 00:00:00 2001 From: "Oriol (ZBook)" Date: Tue, 4 Jan 2022 06:49:50 +0200 Subject: [PATCH 3/3] add section titles to homepage --- examples/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/index.md b/examples/index.md index d35910721..485cbe5a9 100644 --- a/examples/index.md +++ b/examples/index.md @@ -15,14 +15,14 @@ to ensure notebooks are updated and re-executed at the same pace we publish PyMC releases. Consequently, PyMC has two documentation websites: the versioned docs and the example gallery -**Versioned docs** +## Versioned docs We publish the versioned docs directly at `docs.pymc.io`. The only additions to the url are the language and version of the documentation. The versioned docs are synced with PyMC releases and contain a handful of guides about core functionality and the API documentation among other things. -**Example gallery** +## Example gallery We publish the example gallery as a sub-project of the versioned docs: `docs.pymc.io/projects/examples` This means that the building process, language and version of the example gallery are independent from the versioned docs. However, @@ -54,7 +54,7 @@ to include all the relevant metadata. Those notebooks can only be reached from the search bar. ::: -## Categories +### Categories Notebooks have at most two categories, one indicating the level of the notebook and another indicating the type of content according to the [diataxis framework](https://diataxis.fr/). The left sidebar @@ -63,7 +63,7 @@ there to reach the page listing all the notebooks in that category. If a page has some categories in its metadata they are highlighted in green in the category list. -## Tags +### Tags Notebooks can have any number of tags. Each tag represents a specific topic of potential interest to readers or a pymc object used within that notebook.