improve doc style and add missing examples (#92)

* improve doc style and add missing examples

* fix dependecies

* add missing files

docs/404.md

@@ -0,0 +1,14 @@
+---
+orphan: true
+---
+
+# Page not found
+
+**Sorry, we could not find this page**
+
+Click on the navigation bar on top of the page to go to the right section
+of the default docs, or alternatively:
+
+* Go to the current [PyMC example gallery homepage](https://www.pymc.io/projects/examples/en/latest/)
+* Go to the PyMC3 3.x snapshot of the [PyMC example gallery](https://www.pymc.io/projects/examples/en/2022.01.0/)
+  (also available for each page from the version switcher at the bottom right of the page)

docs/api_reference.rst

@@ -13,4 +13,4 @@ methods in the current release of PyMC-BART.
 =============================
 
 .. automodule:: pymc_bart
-   :members: BART, PGBART, plot_dependence, plot_variable_importance, predict
+   :members: BART, PGBART, plot_pdp, plot_variable_importance, plot_convergence

docs/conf.py

@@ -1,200 +1,158 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-# -- 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
-
-from pymc_bart import __version__
-
-sys.path.insert(0, os.path.abspath("../"))
+import os, sys
+from pathlib import Path
+from sphinx.application import Sphinx
 
 # -- Project information -----------------------------------------------------
-
-project = "pymc_bart"
-copyright = "2022, pymc-devs"
-author = "pymc-devs"
-
-# The short X.Y version
-version = __version__
-# The full version, including alpha/beta/rc tags
-release = __version__
-
+project = "PyMC-BART"
+copyright = "2022, PyMC Community"
+author = "PyMC Community"
 
 # -- General configuration ---------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+sys.path.insert(0, os.path.abspath("../sphinxext"))
 
 # 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.autodoc",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
-    "nbsphinx",
+    "myst_nb",
+    "sphinx_design",
+    "sphinxcontrib.bibtex",
+    "sphinx_codeautolink",
+    "sphinx_remove_toctrees",
 ]
 
-external_docs = ["examples/BART_introduction.ipynb", "examples/references.bib"]
-for doc in external_docs:
-    if os.path.exists(doc):
-        os.remove(doc)
+# 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/*",
+    "**/*.myst.md",
+]
+
+if os.path.exists("examples"):
+    external_docs = os.listdir("examples")
+    for doc in external_docs:
+        file = Path("examples", doc) 
+        if os.path.exists(file):
+            os.remove(file)
 
 os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/case_studies/BART_introduction.ipynb -P examples")
+os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/case_studies/BART_quantile_regression.ipynb -P examples")
+os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/case_studies/bart_heteroscedasticity.ipynb -P examples")
 os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/references.bib -P examples")
 
 # bibtex config
-bibtex_bibfiles = ["references.bib"]
+bibtex_bibfiles = ["examples/references.bib"]
 bibtex_default_style = "unsrt"
 bibtex_reference_style = "author_year"
 
-nbsphinx_execute = "never"
-
-# Add any paths that contain templates here, relative to this directory.
-# templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = ['.rst', '.md']
-
-# The master toctree document.
-master_doc = "index"
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# 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", "**.ipynb_checkpoints"]
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = "pydata_sphinx_theme"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-
-# https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#remove-the-sidebar-from-some-pages
 
+# theme options
+html_theme = "pymc_sphinx_theme"
 html_theme_options = {
-    "collapse_navigation": True,
-    "show_toc_level": 2,
-    "navigation_depth": 4,
-    "search_bar_text": "Search the docs...",
-    "icon_links": [
-        {
-            "name": "GitHub",
-            "url": "https://github.com/pymc-devs/pymc-bart",
-            "icon": "fab fa-github-square",
-        },
-    ],
+    "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink", "donate"],
+    "navbar_start": ["navbar-logo"],
+}
+version = os.environ.get("READTHEDOCS_VERSION", "")
+version = version if "." in version else "main"
+html_context = {
+    "github_url": "https://github.com",
+    "github_user": "pymc-devs",
+    "github_repo": "pymc-bart",
+    "github_version": version,
+    "default_mode": "light",
 }
 
+
+html_favicon = "../_static/PyMC.ico"
+html_logo = "../_static/PyMC.png"
+html_title = "PyMC-BART"
+
 # 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"]
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "pymc_bartdoc"
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+html_static_path = ["../_static"]
+html_extra_path = ["../_thumbnails"]
+templates_path = ["../_templates"]
+html_sidebars = {
+    "**": [
+        "sidebar-nav-bs.html",
+    ],
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "pymc_bart.tex", "pymc_bart Documentation", "The developers of pymc_bart", "manual"),
-]
-
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "pymc_bart", "pymc_bart Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "pymc_bart",
-        "pymc_bart Documentation",
-        author,
-        "pymc_bart",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
+# MyST config
+myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath", "substitution"]
+citation_code = f"""
+```bibtex
+@incollection{{citekey,
+  author    = "<notebook authors, see above>",
+  title     = "<notebook title>",
+  editor    = "PyMC Team",
+  booktitle = "PyMC examples",
+}}
+```
+"""
+
+
+myst_substitutions = {
+    "pip_dependencies": "{{ extra_dependencies }}",
+    "conda_dependencies": "{{ extra_dependencies }}",
+    "extra_install_notes": "",
+    "citation_code": citation_code,
+}
+nb_execution_mode = "off"
+
+
+remove_from_toctrees = [
+    "BART/*",
+    "case_studies/*",
+    "causal_inference/*",
+    "diagnostics_and_criticism/*",
+    "gaussian_processes/*",
+    "generalized_linear_models/*",
+    "mixture_models/*",
+    "ode_models/*",
+    "howto/*",
+    "samplers/*",
+    "splines/*",
+    "survival_analysis/*",
+    "time_series/*",
+    "variational_inference/*",
 ]
 
+# bibtex config
+bibtex_bibfiles = ["references.bib"]
+bibtex_default_style = "unsrt"
+bibtex_reference_style = "author_year"
 
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ''
-
-# A unique identification for the text.
-#
-# epub_uid = ''
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
-
-
-# -- Extension configuration -------------------------------------------------
-# https://svn.python.org/projects/external/Jinja-1.1/docs/build/designerdoc.html
+# OpenGraph config
+# use default readthedocs integration aka no config here
+
+codeautolink_autodoc_inject = False
+codeautolink_concat_default = True
+
+# intersphinx mappings
+intersphinx_mapping = {
+    "arviz": ("https://python.arviz.org/en/latest/", None),
+    "bambi": ("https://bambinos.github.io/bambi", None),
+    "einstats": ("https://einstats.python.arviz.org/en/latest/", None),
+    "mpl": ("https://matplotlib.org/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "pymc": ("https://www.pymc.io/projects/docs/en/stable/", None),
+    "pytensor": ("https://pytensor.readthedocs.io/en/latest/", None),
+    "pmx": ("https://www.pymc.io/projects/experimental/en/latest/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+}

docs/examples.rst

@@ -0,0 +1,9 @@
+Examples
+********
+
+.. toctree::
+  :maxdepth: 1
+
+  examples/BART_introduction
+  examples/BART_quantile_regression
+  examples/bart_heteroscedasticity

docs/index.rst

@@ -82,7 +82,7 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   examples/BART_introduction
+   examples
    api_reference
 
 Indices

requirements-docs.txt

@@ -1,3 +1,8 @@
-nbsphinx>=0.4.2
-pydata-sphinx-theme>=0.6.3
-sphinx==5.3.0
+myst-nb
+sphinx==5.0.2 # see https://github.com/pymc-devs/pymc-examples/issues/409
+git+https://github.com/pymc-devs/pymc-sphinx-theme
+sphinxcontrib-bibtex
+nbsphinx
+sphinx_design
+sphinx_codeautolink
+sphinx_remove_toctrees

requirements.txt

@@ -1,4 +1,4 @@
 pymc>=5.0.0
 arviz
 numba
-matplotlib<=3.5.2
+matplotlib