modify layout and add homepage (pymc-devs#260)

* modify the layout * Apply suggestions from code review Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com> * add section titles to homepage Co-authored-by: Thomas Wiecki <thomas.wiecki@gmail.com>
martiningram · Jan 8, 2022 · eaf575a · eaf575a
1 parent 0c684dd
commit eaf575a
Show file tree

Hide file tree

Showing 6 changed files with 157 additions and 29 deletions.
diff --git a/_static/custom.css 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
@@ -1,30 +1,17 @@
 {% if pagename in ablog %}
-  {% set fa = ablog.fontawesome %}
   {% set post = ablog[pagename] %}
-  <h3>Notebook metadata</h3>
 
-  <ul>
-  {% if post.category %}
-    <li id="category">
-    <span><i class="fa-fw fa fa-folder-open"></i></span>
-    {% for coll in post.category %} {% if coll|length %}
-      <a href="{{ pathto(coll.docname) }}">{{ coll }}</a>{% if loop.index <
-      post.category|length %},{% endif %} {% else %}{{ coll }}{% if loop.index <
-      post.category|length %},{% endif %}{% endif %} {% endfor %}
-    </li>
-  {% endif %}
   {% if post.tags %}
-    <li id="tags">
+  <div class="sd-text-muted pt-5 tocsection" style="font-size: .9rem">
     <span>
-      {% if post.tags|length > 1 %}<i class="fa-fw fa fa-tags"></i>
-      {% else %}<i class="fa-fw fa fa-tag"></i>
+      {% if post.tags|length > 1 %}<i class="fas fa-tags"></i>
+      {% else %}<i class="fas fa-tag"></i>
       {% endif %}
     </span>
     {% for coll in post.tags %} {% if coll|length %}
     <a href="{{ pathto(coll.docname) }}">{{ coll }}</a>{% if loop.index <
     post.tags|length %}{% endif %} {% else %}{{ coll }}{% if loop.index <
     post.tags|length %}{% endif %}{% endif %} {% endfor %}
-  </li>
+  </div>
   {% endif %}
-  </ul>
 {% endif %}
diff --git a/_templates/postcard_categories.html 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) -%}
+  <a href="{{ pathtocategory(name) }}" class="{{ setcolorclass(active) }}">
+    <span class="fas {{ icon }}"></span>
+    <label class="sr-only">{{ name }}</label>
+  </a>
+{%- endmacro -%}
+
+<!-- {% set post = "" %} -->
+<!-- {% if pagename in ablog %} -->
+{% set post = ablog[pagename] %}
+<!-- {% endif %} -->
+
+<h3>
+  <a href="{{ pathto(ablog.category.path) }}">{{ gettext('Categories') }}</a>
+</h3>
+<div id="category" class="sd-text-justify sd-fs-4 sd-text-muted">
+  <!-- level 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') %}
+  <div class="container">
+    <div class="row">
+      <div class="col">
+        {{ category_item("beginner", "fa-crow", b_bool) }}
+      </div>
+      <div class="col">
+        {{ category_item("intermediate", "fa-dove", i_bool) }}
+      </div>
+      <div class="col">
+        {{ category_item("advanced", "fa-dragon", a_bool) }}
+      </div>
+    </div>
+  </div>
+
+  <!-- diataxis type categories -->
+  <div class="container sd-fs-6 sd-font-weight-bold">
+    <div class="row border-top border-bottom">
+      {% set t_bool = "tutorial" in post.category|map('string') %}
+      <div class="col {{ setcolorclass(t_bool) }}"><a href="{{ pathtocategory('tutorial') }}">Tutorial</a></div>
+      {% set h_bool = "how-to" in post.category|map('string') %}
+      <div class="col {{ setcolorclass(h_bool) }}"><a href="{{ pathtocategory('how-to') }}">How-to</a></div>
+      <div class="w-100"></div>
+      {% set e_bool = "explanation" in post.category|map('string') %}
+      <div class="col {{ setcolorclass(e_bool) }}"><a href="{{ pathtocategory('explanation') }}">Explanation</a></div>
+      {% set r_bool = "reference" in post.category|map('string') %}
+      <div class="col {{ setcolorclass(r_bool) }}"><a href="{{ pathtocategory('reference') }}">Reference</a></div>
+    </div>
+  </div>
+
+</div>
diff --git a/examples/blog.md b/examples/blog.md
@@ -1,3 +1,3 @@
-# Blog
+# Recent updates
 
 <!-- auto generated by ablog so it's empty -->
diff --git 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
@@ -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 can be tutorials,
+case studies or in-depth explanations.
+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.
+
+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 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 <pymc:search>` 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 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).
+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 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.
+:::
+
+### 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
 :::