working and hopefully illustrative doc skeleton

Author: OriolAbril

docs/source/conf.py

@@ -110,7 +110,7 @@
 
 # myst and panels config
 jupyter_execute_notebooks = "off"
-myst_heading_anchors = 3
+myst_heading_anchors = 2
 myst_enable_extensions = [
     "colon_fence",
 ]
@@ -195,7 +195,12 @@
     "github_version": "main",
     "doc_path": "docs/source/",
 }
-html_sidebars = {"learn": [], "**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"]}
+# this controls which sidebar sections are available in which pages. [] removes the left sidebar
+html_sidebars = {
+    "learn": [],
+    "installation": [],
+    "**": ["sidebar-nav-bs.html", "sidebar-ethical-ads.html"],
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/source/index.md

@@ -1,11 +1,39 @@
 # PyMC3 documentation
 
-Page in construction
+Page in construction.
+
+For now there are only some examples of https://sphinx-design.readthedocs.io/en/sbt-theme/index.html
+usage.
 
 :::{button-ref} learning
+:ref-type: ref
+:color: primary
+:expand:
+
+Getting Started as giant long button
+:::
+
+:::::{grid} 1 1 3 3
+
+:::{grid-item}
+:::
+
+::::{grid-item}
+:::{button-link} https://numfocus.org/donate-to-pymc3
+:expand:
+:color: secondary
 
-Getting Started
+Donate as button within a grid
 :::
+::::
+
+:::{grid-item}
+:::
+:::::
+
+Also add a cool icon: in default size {fas}`check-circle`, or extra large
+{fas}`check-circle;fa-10x`. See https://fontawesome.com/v5.15/how-to-use/on-the-web/styling/sizing-icons
+for options.
 
 :::{toctree}
 :maxdepth: 1

docs/source/installation.md

@@ -5,23 +5,46 @@ Move the 3 wiki pages over to here.
 with sphinx_design we can have common content in a single place,
 and whenever there is some specific guidance that depends on OS use
 tabs, which can be syncronized. That is, if one tab is switched over to
-windows, all tabs will be moved to windows.
+windows, all tabs will be moved to windows. For example:
 
 ::::{tab-set}
 :::{tab-item} Linux
+:sync: linux
 
 specific linux content
 :::
 
 :::{tab-item} MacOS
+:sync: mac
 
 specific macos content
 :::
 
 :::{tab-item} Windows
+:sync: windows
 
 specific windows content
 :::
 ::::
 
 more common content
+
+::::{tab-set}
+:::{tab-item} Linux
+:sync: linux
+
+extra specific linux content, i.e. testing the installation was successful
+:::
+
+:::{tab-item} MacOS
+:sync: mac
+
+extra specific macosx content, i.e. testing the installation was successful
+:::
+
+:::{tab-item} Windows
+:sync: windows
+
+extra specific windows content, i.e. testing the installation was successful
+:::
+::::

docs/source/learn/step1.md

@@ -0,0 +1,6 @@
+# Step 1
+
+Detailed explanation of step 1, which sections of the documentation are indicated
+and which external references are recommended. i.e. to make the most of pymc3, you should
+be familiar with Bayesian statistics. Here are some books whose code is available using pymc3 to
+help you learn Bayesian statistics with pymc3.

docs/source/learn/step2.md

@@ -0,0 +1,28 @@
+# Step 2
+
+Detailed explanation of step 2, which sections of the documentation are indicated
+and which external references are recommended.
+
+::::{grid} 1 2 3 4
+
+:::{grid-item}
+{fas}`info-circle;fa-5x`
+
+{doc}`case_studies/multilevel_modeling`
+:::
+:::{grid-item}
+{fas}`golf-ball;fa-5x`
+
+{doc}`case_studies/putting_workflow`
+:::
+:::{grid-item}
+{fas}`book-open;fa-5x`
+
+{doc}`diagnostics_and_criticism/model_comparison`
+:::
+:::{grid-item}
+{fas}`football-ball;fa-5x`
+
+{doc}`case_studies/rugby_analytics`
+:::
+::::

docs/source/learn/step3.md

@@ -0,0 +1,3 @@
+# Step 3
+
+More content

docs/source/learning.md

@@ -1,16 +1,32 @@
 (learning)=
 # Learning
 
-## Step 1
-Links to books and pymc-devs/resources
+I propose the following pattern to be followed in general.
+Each navbar section (which are the pages listed in the index toctree)
+should have an overview of the contents of the section and a hidden
+toctree to the pages within that section (if any). This will make the
+pages appear in the left sidebar for easy navigation while keeping the
+in page toc on the right sidebar.
+
+## Step 1 overview
+Links to books and pymc-devs/resources.
 
 ---
-## Step 2
+## Step 2 overview
 Links to beginner lever notebooks. For example,
 thanks to intersphinx, we can cite the getting started
-notebook with {doc}`nb:examples/getting_started`
+notebook with {doc}`nb:getting_started` (the path in pymc-examples repo excluding
+the `examples` folder, or using manual anchors if we decide to create them).
 
 ---
-## Step 3
+## Step 3 overview
+
+Links to intermediate notebooks. {doc}`More about step 3... <learn/step3>`
+
+```{toctree}
+:hidden:
 
-Links to intermediate notebooks
+learn/step1
+learn/step2
+learn/step3
+```