Initialize standalone build (#218)

* Initialize standalone build

* couple minor fixes to trigger readthedocs

* extend contributing docs

* review suggesions

Author: OriolAbril

.gitignore

@@ -1,3 +1,6 @@
 *.pyc
 .ipynb_checkpoints
 .vscode/*
+
+_build
+jupyter_execute

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+
+sphinx:
+    configuration: examples/conf.py
+
+python:
+   version: "3.8"
+   install:
+   - requirements: requirements-docs.txt
+   - method: pip
+     path: .

CONTRIBUTING.md

@@ -106,3 +106,18 @@ We recommended that your contribution complies with the following guidelines bef
 * No `pre-commit` errors: see the [Jupyter Notebook style](https://github.com/pymc-devs/pymc3/wiki/PyMC3-Jupyter-Notebook-Style-Guide) (and [Python code style](https://github.com/pymc-devs/pymc3/wiki/PyMC3-Python-Code-Style)) page from our Wiki on how to install and run it.
 
 * Indicate how are you aiming to update the notebook (i.e. what is the target end column in the tracker). The pull request template has a template for this.
+
+## Contributor guide
+In order to work and run the example notebooks you need to install the packages in
+`requirements-write.txt`. To see how the notebook looks rendered, you can follow
+the instructions in the following paragraph or open a PR to see the preview in
+readthedocs.
+
+The markdown cells in the notebook can use MyST, a superset of CommonMark markdown. See
+https://myst-parser.readthedocs.io/en/latest/ and https://myst-nb.readthedocs.io/en/latest/
+for documentation on their features and syntax.
+
+To generate the draft standalone notebook gallery, you need to have installed all the packages in
+`requirements-docs.txt` and to run `sphinx-build examples/ _build -b html` from the repository
+home directory. After building, you can see the preview of the docs
+by opening `_build/index.html` file with your browser.

_static/PyMC3.ico

@@ -0,0 +1,6 @@
+# General Bibliography
+
+:::{bibliography}
+:all:
+
+:::

examples/bibliography.md

@@ -0,0 +1,3 @@
+# Blog
+
+<!-- auto generated by ablog so it's empty -->

examples/blog.md

@@ -4,7 +4,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# A Primer on Bayesian Methods for Multilevel Modeling"
+    "# A Primer on Bayesian Methods for Multilevel Modeling\n",
+    "\n",
+    ":::{post} 30 Aug, 2021\n",
+    ":tags: hierarchical\n",
+    ":category: intermediate\n",
+    ":::"
    ]
   },
   {
@@ -20,7 +25,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Example: Radon contamination (Gelman and Hill 2006)\n",
+    "## Example: Radon contamination {cite:t}`gelman2006data`\n",
     "\n",
     "Radon is a radioactive gas that enters homes through contact points with the ground. It is a carcinogen that is the primary cause of lung cancer in non-smokers. Radon levels vary greatly from household to household.\n",
     "\n",
@@ -8498,11 +8503,19 @@
     "\n",
     "## References\n",
     "\n",
-    "- Gelman, A., & Hill, J. (2006), *Data Analysis Using Regression and Multilevel/Hierarchical Models (1st ed.)*, Cambridge University Press.\n",
-    "\n",
-    "- Gelman, A. (2006), *Multilevel (Hierarchical) modeling: what it can and cannot do*, Technometrics, 48(3), 432–435.\n",
+    ":::{bibliography}\n",
+    ":filter: docname in docnames\n",
     "\n",
-    "- McElreath, R. (2020), *Statistical Rethinking - A Bayesian Course with Examples in R and Stan (2nd ed.)*, CRC Press. "
+    "gelman2006multilevel\n",
+    "mcelreath2018statistical\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Watermark"
    ]
   },
   {
@@ -8543,7 +8556,7 @@
  "metadata": {
   "celltoolbar": "Raw Cell Format",
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -8557,7 +8570,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.9"
+   "version": "3.8.6"
   }
  },
  "nbformat": 4,

examples/case_studies/multilevel_modeling.ipynb

@@ -4,7 +4,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# A Hierarchical model for Rugby prediction"
+    "# A Hierarchical model for Rugby prediction\n",
+    "\n",
+    ":::{post} 30 Aug, 2021\n",
+    ":tags: hierarchical, sports\n",
+    ":category: intermediate\n",
+    ":::"
    ]
   },
   {
@@ -2424,7 +2429,7 @@
  "metadata": {
   "anaconda-cloud": {},
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -2438,7 +2443,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.2"
+   "version": "3.8.6"
   }
  },
  "nbformat": 4,

examples/case_studies/rugby_analytics.ipynb

@@ -0,0 +1,135 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "PyMC3"
+copyright = "2021, PyMC Community"
+author = "PyMC Community"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "myst_nb",
+    "ablog",
+    "sphinx_design",
+    "sphinxext.opengraph",
+    "sphinx_copybutton",
+    "sphinxcontrib.bibtex",
+]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "*import_posts*",
+    "**/.ipynb_checkpoints/*",
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+# theme options
+html_theme = "pydata_sphinx_theme"
+html_theme_options = {
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/pymc-devs/pymc-examples",
+            "icon": "fab fa-github-square",
+        },
+        {
+            "name": "Twitter",
+            "url": "https://twitter.com/pymc-devs",
+            "icon": "fab fa-twitter-square",
+        },
+        {
+            "name": "Discourse",
+            "url": "https://discourse.pymc.io",
+            "icon": "fab fa-discourse",
+        },
+    ],
+    "search_bar_text": "Search...",
+    "navbar_end": ["search-field.html", "navbar-icon-links.html"],
+    "external_links": [
+        {"name": "Learning", "url": "https://pymc3.readthedocs.io/en/latest/learn.html"},
+        {"name": "API", "url": "https://pymc3.readthedocs.io/en/latest/api.html"}
+    ]
+}
+
+html_favicon = "../_static/PyMC3.ico"
+
+# 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"]
+html_sidebars = {
+    "**": ["sidebar-nav-bs.html", "tagcloud.html", "categories.html"],
+}
+
+# ablog config
+# blog_baseurl = "https://predictablynoisy.com"
+blog_title = "PyMC Examples"
+blog_path = "blog"
+# fontawesome_included = True
+# post_redirect_refresh = 1
+# post_auto_image = 1
+# post_auto_excerpt = 2
+
+# MyST config
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "amsmath"
+]
+
+# bibtex config
+bibtex_bibfiles = ['references.bib']
+bibtex_default_style = 'unsrt'
+bibtex_reference_style = "author_year"
+
+# OpenGraph config
+# ogp_site_url = "https://predictablynoisy.com"
+# ogp_image = "https://predictablynoisy.com/_static/profile-bw.png"
+
+# Temporarily stored as off until we fix it
+jupyter_execute_notebooks = "off"
+
+# intersphinx mappings
+intersphinx_mapping = {
+    "aesara": ("https://aesara.readthedocs.io/en/latest/", None),
+    "arviz": ("https://arviz-devs.github.io/arviz/", None),
+    # "mpl": ("https://matplotlib.org/", None),
+    # "numpy": ("https://numpy.org/doc/stable/", None),
+    # "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "pymc3": ("https://docs.pymc.io/", None),
+    # "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    # "xarray": ("http://xarray.pydata.org/en/stable/", None),
+}