Skip to content

Commit eaf575a

Browse files
OriolAbriltwiecki
OriolAbril
and
twiecki
authored
modify layout and add homepage (#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>
1 parent 0c684dd commit eaf575a

File tree

6 files changed

+157
-29
lines changed

6 files changed

+157
-29
lines changed

‎_static/custom.css

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/* taken from sphinx-codeautolink examples */
2+
.sphinx-codeautolink-a{
3+
border-bottom-color: rgb(0, 0, 0);
4+
border-bottom-style: dotted;
5+
border-bottom-width: 1px;
6+
}
7+
.sphinx-codeautolink-a:hover{
8+
color: rgb(255, 139, 139);
9+
}
10+
11+
.bd-sidebar {
12+
overflow-y: auto;
13+
}

‎_templates/postcard.html

Lines changed: 4 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,17 @@
11
{% if pagename in ablog %}
2-
{% set fa = ablog.fontawesome %}
32
{% set post = ablog[pagename] %}
4-
<h3>Notebook metadata</h3>
53

6-
<ul>
7-
{% if post.category %}
8-
<li id="category">
9-
<span><i class="fa-fw fa fa-folder-open"></i></span>
10-
{% for coll in post.category %} {% if coll|length %}
11-
<a href="{{ pathto(coll.docname) }}">{{ coll }}</a>{% if loop.index <
12-
post.category|length %},{% endif %} {% else %}{{ coll }}{% if loop.index <
13-
post.category|length %},{% endif %}{% endif %} {% endfor %}
14-
</li>
15-
{% endif %}
164
{% if post.tags %}
17-
<li id="tags">
5+
<div class="sd-text-muted pt-5 tocsection" style="font-size: .9rem">
186
<span>
19-
{% if post.tags|length > 1 %}<i class="fa-fw fa fa-tags"></i>
20-
{% else %}<i class="fa-fw fa fa-tag"></i>
7+
{% if post.tags|length > 1 %}<i class="fas fa-tags"></i>
8+
{% else %}<i class="fas fa-tag"></i>
219
{% endif %}
2210
</span>
2311
{% for coll in post.tags %} {% if coll|length %}
2412
<a href="{{ pathto(coll.docname) }}">{{ coll }}</a>{% if loop.index <
2513
post.tags|length %}{% endif %} {% else %}{{ coll }}{% if loop.index <
2614
post.tags|length %}{% endif %}{% endif %} {% endfor %}
27-
</li>
15+
</div>
2816
{% endif %}
29-
</ul>
3017
{% endif %}

‎_templates/postcard_categories.html

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
{%- macro pathtocategory(category) -%}
2+
{% set path = "blog/category/" + category %}
3+
{{ pathto(path) }}
4+
{%- endmacro -%}
5+
6+
{%- macro setcolorclass(active) -%}
7+
{% if active %}
8+
{{ "sd-text-success" }}
9+
{% else %}
10+
{{ "sd-text-muted" }}
11+
{% endif %}
12+
{%- endmacro -%}
13+
14+
15+
{%- macro category_item(name, icon, active) -%}
16+
<a href="{{ pathtocategory(name) }}" class="{{ setcolorclass(active) }}">
17+
<span class="fas {{ icon }}"></span>
18+
<label class="sr-only">{{ name }}</label>
19+
</a>
20+
{%- endmacro -%}
21+
22+
<!-- {% set post = "" %} -->
23+
<!-- {% if pagename in ablog %} -->
24+
{% set post = ablog[pagename] %}
25+
<!-- {% endif %} -->
26+
27+
<h3>
28+
<a href="{{ pathto(ablog.category.path) }}">{{ gettext('Categories') }}</a>
29+
</h3>
30+
<div id="category" class="sd-text-justify sd-fs-4 sd-text-muted">
31+
<!-- level categories -->
32+
{% set i_bool = "intermediate" in post.category|map('string') %}
33+
{% set b_bool = "beginner" in post.category|map('string') %}
34+
{% set a_bool = "advanced" in post.category|map('string') %}
35+
<div class="container">
36+
<div class="row">
37+
<div class="col">
38+
{{ category_item("beginner", "fa-crow", b_bool) }}
39+
</div>
40+
<div class="col">
41+
{{ category_item("intermediate", "fa-dove", i_bool) }}
42+
</div>
43+
<div class="col">
44+
{{ category_item("advanced", "fa-dragon", a_bool) }}
45+
</div>
46+
</div>
47+
</div>
48+
49+
<!-- diataxis type categories -->
50+
<div class="container sd-fs-6 sd-font-weight-bold">
51+
<div class="row border-top border-bottom">
52+
{% set t_bool = "tutorial" in post.category|map('string') %}
53+
<div class="col {{ setcolorclass(t_bool) }}"><a href="{{ pathtocategory('tutorial') }}">Tutorial</a></div>
54+
{% set h_bool = "how-to" in post.category|map('string') %}
55+
<div class="col {{ setcolorclass(h_bool) }}"><a href="{{ pathtocategory('how-to') }}">How-to</a></div>
56+
<div class="w-100"></div>
57+
{% set e_bool = "explanation" in post.category|map('string') %}
58+
<div class="col {{ setcolorclass(e_bool) }}"><a href="{{ pathtocategory('explanation') }}">Explanation</a></div>
59+
{% set r_bool = "reference" in post.category|map('string') %}
60+
<div class="col {{ setcolorclass(r_bool) }}"><a href="{{ pathtocategory('reference') }}">Reference</a></div>
61+
</div>
62+
</div>
63+
64+
</div>

‎examples/blog.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
# Blog
1+
# Recent updates
22

33
<!-- auto generated by ablog so it's empty -->

‎examples/conf.py

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@
6868
{"name": "Learning", "url": "https://docs.pymc.io/en/stable/learn.html"},
6969
{"name": "API", "url": "https://docs.pymc.io/en/stable/api.html"},
7070
],
71+
"page_sidebar_items": ["postcard", "page-toc", "edit-this-page"],
7172
}
7273
version = os.environ.get("READTHEDOCS_VERSION", "")
7374
version = version if "-" in version else "main"
@@ -90,15 +91,13 @@
9091
# relative to this directory. They are copied after the builtin static files,
9192
# so a file named "default.css" will overwrite the builtin "default.css".
9293
html_static_path = ["../_static"]
94+
html_css_files = ["custom.css"]
9395
templates_path = ["../_templates"]
94-
# Workaround to make the whole sidebar scrollable. See https://github.com/pydata/pydata-sphinx-theme/issues/500
95-
# ideally the tagcloud, categories and ads would be added from here in conf.py
9696
html_sidebars = {
9797
"**": [
9898
# "sidebar-nav-bs.html",
99-
"postcard.html",
99+
"postcard_categories.html",
100100
"tagcloud.html",
101-
"categories.html",
102101
"sidebar-ethical-ads.html",
103102
],
104103
}

‎examples/index.md

Lines changed: 72 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,79 @@
11
# PyMC example gallery
22

3-
This is a WIP website.
3+
**Welcome to the PyMC example gallery!**
44

5-
This homepage is temporarily empty while we format and categorize
6-
all example notebooks as posts. You can see the tags and
7-
categories on the left sidebar and reach the already updated notebooks
8-
from there. All notebooks are rendered in the website though, you can access them
9-
via the search bar.
5+
The PyMC example gallery is a collection of Jupyter notebooks
6+
about PyMC and its usage. These notebooks can be tutorials,
7+
case studies or in-depth explanations.
8+
Some notebooks were originally blog posts, others were adapted from books
9+
and some were written specifically for this example gallery.
10+
This homepage explains the organization of the website and provides
11+
some pointers on how to navigate it.
12+
13+
The collection contains more than 90 notebooks. We are therefore unable
14+
to ensure notebooks are updated and re-executed at the same pace we
15+
publish PyMC releases. Consequently, PyMC has two documentation
16+
websites: the versioned docs and the example gallery
17+
18+
## Versioned docs
19+
We publish the versioned docs directly at `docs.pymc.io`. The only additions
20+
to the url are the language and version of the documentation.
21+
22+
The versioned docs are synced with PyMC releases and contain a handful of
23+
guides about core functionality and the API documentation among other things.
24+
25+
## Example gallery
26+
We publish the example gallery as a sub-project of the versioned docs: `docs.pymc.io/projects/examples`
27+
This means that the building process, language and version of the
28+
example gallery are independent from the versioned docs. However,
29+
the {ref}`search bar in the versioned docs <pymc:search>` searches
30+
both the versioned docs and the example gallery at the same time
31+
(but not the other way around).
32+
33+
We will update the notebooks in the example gallery regularly
34+
and publish the updates to the example gallery website with each commit.
35+
We recommend using the example gallery as an unversioned living
36+
resource, but we will also provide snapshots every few months for cases such as books
37+
that need links to a stable resource.
38+
39+
You can access the snapshots from the version menu at the bottom right of the page.
40+
A version number in the `YYYY.0M.MICRO` format identifies the time the snapshot was published.
41+
42+
---
43+
44+
Notebooks are treated as blog posts. The metadata of each notebook
45+
describes its topics and type of content via tags and categories
46+
and the last update date. We believe that tags and categories
47+
ease and improve navigation (as opposed to a fixed topic division/hierarchy).
48+
In addition, we also provide a list of recent updates and a search bar in the
49+
navigation bar at the top of the page.
50+
51+
:::{caution}
52+
The website is still under construction. Thus, not all notebooks have been updated
53+
to include all the relevant metadata. Those notebooks can only be reached
54+
from the search bar.
55+
:::
56+
57+
### Categories
58+
Notebooks have at most two categories, one indicating the level of the
59+
notebook and another indicating the type of content according to the
60+
[diataxis framework](https://diataxis.fr/). The left sidebar
61+
shows all 7 categories (3 levels + 4 types) at all times. You can click
62+
there to reach the page listing all the notebooks in that category.
63+
If a page has some categories in its metadata they are highlighted in green
64+
in the category list.
65+
66+
### Tags
67+
Notebooks can have any number of tags. Each tag represents a specific topic
68+
of potential interest to readers or a pymc object used within that notebook.
69+
70+
The left sidebar shows all tags at all times. Like categories, they can be clicked
71+
on to reach the page listing all notebooks that contain the tag. If a notebook
72+
has tags in its metadata they are listed on the right sidebar after the {fas}`tags` icon.
1073

1174
:::{toctree}
12-
:maxdepth: 2
75+
:maxdepth: 1
76+
:hidden:
77+
1378
blog
1479
:::

0 commit comments

Comments
 (0)