Restructure docs.pymc.io, add developer guide (#3311)

* [WIP] Restructure docs.pymc.io, add developer guide Following #3303, this is a further restructure of our website. - Tutorial page include all our high level API guides (including theano.rst, prod_dist.rst, gp.rst etc) - renaming of some notebooks (some of them does not have title) - notebooks might appear under more than 1 categories (if it covers multiple topics) * Further formatting * Add developer guide * edit developer guide * small formatting * further formatting * final formatting * really final formatting * fix links * small edit + another proof reading * formatting
pymc-devs · Dec 19, 2018 · ff1227b · ff1227b
1 parent fc523cc
commit ff1227b
Show file tree

Hide file tree

Showing 11 changed files with 1,200 additions and 100 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -147,6 +147,7 @@
         ("Examples", "nb_examples/index"),
         ("Books + Videos", "learn"),
         ("API", "api"),
+        ("Developer Guide", "developer_guide"),
         ("About PyMC3", "history")
     ],
     #     "fixed_sidebar": "false",

diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,10 +10,10 @@
                     <h3 class="ui header">Friendly modelling API</h3>
                     <p>PyMC3 allows you to write down models using an intuitive syntax to describe a data generating
                         process.</p>
-                    <h3 class="ui header">Cutting edge algorithms</h3>
+                    <h3 class="ui header">Cutting edge algorithms and model building blocks</h3>
                     <p>Fit your model using gradient-based MCMC algorithms like NUTS, using ADVI for fast approximate
                         inference &mdash; including minibatch-ADVI for scaling to large datasets &mdash; or using
-                        Gaussian processes to fit a regression model.</p>
+                        Gaussian processes to build Bayesian nonparametric models.</p>
                 </div>
                 <div class="eight wide right floated column">
 

diff --git a/docs/source/notebooks/GLM.ipynb b/docs/source/notebooks/GLM.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# GLM: Linear Regression"
+    "# (Generalized) Linear and Hierarchical Linear Models in PyMC3"
    ]
   },
   {
@@ -28,8 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Simple example\n",
-    "==============\n",
+    "## Linear Regression\n",
     "\n",
     "Lets generate some data with known slope and intercept and fit a simple linear GLM."
    ]
@@ -146,8 +145,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Robust GLM\n",
-    "==========\n",
+    "## Robust GLM\n",
     "\n",
     "Lets try the same model but with a few outliers in the data."
    ]
@@ -255,7 +253,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Hierarchical GLM"
+    "## Hierarchical GLM"
    ]
   },
   {
@@ -452,7 +450,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Logistic Regression"
+    "## Logistic Regression"
    ]
   },
   {

diff --git a/docs/source/notebooks/MvGaussianRandomWalk_demo.ipynb b/docs/source/notebooks/MvGaussianRandomWalk_demo.ipynb
diff --git a/docs/source/notebooks/api_quickstart.ipynb b/docs/source/notebooks/api_quickstart.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# API quickstart"
+    "# General API quickstart"
    ]
   },
   {

diff --git a/docs/source/notebooks/cox_model.ipynb b/docs/source/notebooks/cox_model.ipynb
@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Cox model"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -284,7 +291,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.1"
+   "version": "3.6.5"
   },
   "latex_envs": {
    "bibliofile": "biblio.bib",

diff --git a/docs/source/notebooks/gaussian_process.ipynb b/docs/source/notebooks/gaussian_process.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Gaussian Processes\n",
+    "# Gaussian Processes using numpy kernel\n",
     "\n",
     "(c) 2016 by Chris Fonnesbeck"
    ]

diff --git a/docs/source/notebooks/table_of_contents_examples.js b/docs/source/notebooks/table_of_contents_examples.js
@@ -1,21 +1,27 @@
 Gallery.contents = {
-    "AR": "Time Series",
-    "BEST": "Applied",
-    "Bayes_factor": "Other",
-    "Diagnosing_biased_Inference_with_Divergences": "Diagnostics",
-    "Euler-Maruyama_and_SDEs": "Time Series",
-    "GLM-hierarchical-advi-minibatch": "Variational Inference",
-    "GLM-hierarchical-binominal-model": "GLMs",
-    "GLM-hierarchical": "GLMs",
-    "GLM-linear": "GLMs",
-    "GLM-logistic": "GLMs",
-    "GLM-model-selection": "GLMs",
-    "GLM-negative-binomial-regression": "GLMs",
-    "GLM-poisson-regression": "GLMs",
-    "GLM-robust-with-outlier-detection": "GLMs",
-    "GLM-robust": "GLMs",
-    "GLM-rolling-regression": "GLMs",
-    "GLM": "GLMs",
+    "BEST": "Case Studies",
+    "LKJ": "Case Studies",
+    "dawid-skene": "Case Studies",
+    "stochastic_volatility": "Case Studies",
+    "rugby_analytics": "Case Studies",
+    "multilevel_modeling": "Case Studies",
+    "Diagnosing_biased_Inference_with_Divergences": "Diagnostics and Model Criticism",
+    "model_comparison": "Diagnostics and Model Criticism",
+    "posterior_predictive": "Diagnostics and Model Criticism",
+    "Bayes_factor": "Diagnostics and Model Criticism",
+    "GLM": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-linear": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-logistic": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-hierarchical-binominal-model": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-hierarchical": "(Generalized) Linear and Hierarchical Linear Models",
+    "hierarchical_partial_pooling": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-model-selection": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-negative-binomial-regression": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-poisson-regression": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-robust-with-outlier-detection": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-robust": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-rolling-regression": "(Generalized) Linear and Hierarchical Linear Models",
+    "GLM-hierarchical-advi-minibatch": "(Generalized) Linear and Hierarchical Linear Models",
     "GP-Kron": "Gaussian Processes",
     "GP-Latent": "Gaussian Processes",
     "GP-Marginal": "Gaussian Processes",
@@ -26,32 +32,29 @@ Gallery.contents = {
     "GP-TProcess": "Gaussian Processes",
     "GP-slice-sampling": "Gaussian Processes",
     "GP-smoothing": "Gaussian Processes",
-    "MvGaussianRandomWalk_demo": "Time Series",
-    "SMC2_gaussians": "Other",
-    "bayes_param_survival_pymc3": "Survival Analysis",
-    "bayesian_neural_network_advi": "Variational Inference",
-    "bayesian_neural_network_with_sgfs": "Stochastic Gradients",
-    "censored_data": "Survival Analysis",
-    "constant_stochastic_gradient": "Stochastic Gradients",
-    "convolutional_vae_keras_advi": "Variational Inference",
-    "cox_model": "Other",
-    "dawid-skene": "Applied",
+    "gaussian_process": "Gaussian Processes",
     "dependent_density_regression": "Mixture Models",
     "dp_mix": "Mixture Models",
-    "empirical-approx-overview": "Variational Inference",
     "gaussian-mixture-model-advi": "Mixture Models",
     "gaussian_mixture_model": "Mixture Models",
-    "gaussian_process": "Gaussian Processes",
-    "hierarchical_partial_pooling": "GLMs",
-    "lda-advi-aevb": "Variational Inference",
     "marginalized_gaussian_mixture_model": "Mixture Models",
-    "model_comparison": "Diagnostics",
-    "multilevel_modeling": "Applied",
-    "normalizing_flows_overview": "Variational Inference",
-    "posterior_predictive": "Diagnostics",
-    "rugby_analytics": "Applied",
+    "SMC2_gaussians": "Simulation-based Inference",
+    "bayesian_neural_network_with_sgfs": "Stochastic Gradients",
+    "constant_stochastic_gradient": "Stochastic Gradients",
     "sgfs_simple_optimization": "Stochastic Gradients",
-    "stochastic_volatility": "Applied",
+    "bayes_param_survival_pymc3": "Survival Analysis",
+    "censored_data": "Survival Analysis",
     "survival_analysis": "Survival Analysis",
-    "weibull_aft": "Survival Analysis"
+    "weibull_aft": "Survival Analysis",
+    "cox_model": "Survival Analysis",
+    "MvGaussianRandomWalk_demo": "Time Series",
+    "AR": "Time Series",
+    "Euler-Maruyama_and_SDEs": "Time Series",
+    "bayesian_neural_network_advi": "Variational Inference",
+    "convolutional_vae_keras_advi": "Variational Inference",
+    "empirical-approx-overview": "Variational Inference",
+    "lda-advi-aevb": "Variational Inference",
+    "normalizing_flows_overview": "Variational Inference",
+    "gaussian-mixture-model-advi": "Variational Inference",
+    "GLM-hierarchical-advi-minibatch": "Variational Inference"
 }
diff --git a/docs/source/notebooks/table_of_contents_tutorials.js b/docs/source/notebooks/table_of_contents_tutorials.js
@@ -1,16 +1,20 @@
 Gallery.contents = {
     "api_quickstart": "Basics",
-    "getting_started": "Basics",
-    "sampler-stats": "Basics",
-    "sampling_compound_step": "Basics",
-    "howto_debugging": "Basics",
-    "live_sample_plots": "How-To",
+    "variational_api_quickstart": "Basics",
+    "theano": "Basics",
+    "prob_dists": "Basics",
+    "gp": "Basics",
+    "sampling_compound_step": "Deep dives",
+    "sampler-stats": "Deep dives",
+    "Diagnosing_biased_Inference_with_Divergences": "Deep dives",
+    "advanced_theano": "Deep dives",
+    "getting_started": "Deep dives",
+    "PyMC3_tips_and_heuristic": "How-To",
+    "blackbox_external_likelihood": "How-To",
     "profiling": "How-To",
-    "updating_priors": "How-To",
-    "lasso_block_update": "How-To",
+    "howto_debugging": "How-To",
     "model_averaging": "How-To",
-    "blackbox_external_likelihood": "How-To",
-    "LKJ": "How-To",
-    "variational_api_quickstart": "How-To",
-    "PyMC3_tips_and_heuristic": "How-To"
+    "updating_priors": "How-To",
+    "live_sample_plots": "How-To",
+    "lasso_block_update": "How-To"
 }
diff --git a/docs/source/prob_dists.rst b/docs/source/prob_dists.rst
@@ -1,8 +1,8 @@
 .. _prob_dists:
 
-*************************
-Probability Distributions
-*************************
+**********************************
+Probability Distributions in PyMC3
+**********************************
 
 The most fundamental step in building Bayesian models is the specification of a full probability model for the problem at hand. This primarily involves assigning parametric statistical distributions to unknown quantities in the model, in addition to appropriate functional forms for likelihoods to represent the information from the data. To this end, PyMC3 includes a comprehensive set of pre-defined statistical distributions that can be used as model building blocks.