Skip to content

Commit 5edcf19

Browse files
aloctavodiaaloctavodia
authored
improve doc style and add missing examples (#92)
* improve doc style and add missing examples * fix dependecies * add missing files
1 parent d1bb5b7 commit 5edcf19

File tree

7 files changed

+155
-169
lines changed

7 files changed

+155
-169
lines changed

‎docs/404.md

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

‎docs/api_reference.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,4 @@ methods in the current release of PyMC-BART.
1313
=============================
1414

1515
.. automodule:: pymc_bart
16-
:members: BART, PGBART, plot_dependence, plot_variable_importance, predict
16+
:members: BART, PGBART, plot_pdp, plot_variable_importance, plot_convergence

‎docs/conf.py

+121-163
Original file line numberDiff line numberDiff line change
@@ -1,200 +1,158 @@
1-
# -*- coding: utf-8 -*-
2-
#
3-
# Configuration file for the Sphinx documentation builder.
4-
#
5-
# This file does only contain a selection of the most common options. For a
6-
# full list see the documentation:
7-
# http://www.sphinx-doc.org/en/master/config
8-
9-
# -- Path setup --------------------------------------------------------------
10-
11-
# If extensions (or modules to document with autodoc) are in another directory,
12-
# add these directories to sys.path here. If the directory is relative to the
13-
# documentation root, use os.path.abspath to make it absolute, like shown here.
14-
#
15-
import os
16-
import sys
17-
18-
from pymc_bart import __version__
19-
20-
sys.path.insert(0, os.path.abspath("../"))
1+
import os, sys
2+
from pathlib import Path
3+
from sphinx.application import Sphinx
214

225
# -- Project information -----------------------------------------------------
23-
24-
project = "pymc_bart"
25-
copyright = "2022, pymc-devs"
26-
author = "pymc-devs"
27-
28-
# The short X.Y version
29-
version = __version__
30-
# The full version, including alpha/beta/rc tags
31-
release = __version__
32-
6+
project = "PyMC-BART"
7+
copyright = "2022, PyMC Community"
8+
author = "PyMC Community"
339

3410
# -- General configuration ---------------------------------------------------
3511

36-
# If your documentation needs a minimal Sphinx version, state it here.
37-
#
38-
# needs_sphinx = '1.0'
12+
sys.path.insert(0, os.path.abspath("../sphinxext"))
3913

4014
# Add any Sphinx extension module names here, as strings. They can be
4115
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4216
# ones.
4317
extensions = [
44-
"sphinx.ext.autodoc",
45-
"sphinx.ext.viewcode",
46-
"sphinx.ext.napoleon",
18+
"sphinx.ext.intersphinx",
4719
"sphinx.ext.mathjax",
48-
"nbsphinx",
20+
"myst_nb",
21+
"sphinx_design",
22+
"sphinxcontrib.bibtex",
23+
"sphinx_codeautolink",
24+
"sphinx_remove_toctrees",
4925
]
5026

51-
external_docs = ["examples/BART_introduction.ipynb", "examples/references.bib"]
52-
for doc in external_docs:
53-
if os.path.exists(doc):
54-
os.remove(doc)
27+
# List of patterns, relative to source directory, that match files and
28+
# directories to ignore when looking for source files.
29+
# This pattern also affects html_static_path and html_extra_path.
30+
exclude_patterns = [
31+
"_build",
32+
"Thumbs.db",
33+
".DS_Store",
34+
"*import_posts*",
35+
"**/.ipynb_checkpoints/*",
36+
"**/*.myst.md",
37+
]
38+
39+
if os.path.exists("examples"):
40+
external_docs = os.listdir("examples")
41+
for doc in external_docs:
42+
file = Path("examples", doc)
43+
if os.path.exists(file):
44+
os.remove(file)
5545

5646
os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/case_studies/BART_introduction.ipynb -P examples")
47+
os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/case_studies/BART_quantile_regression.ipynb -P examples")
48+
os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/case_studies/bart_heteroscedasticity.ipynb -P examples")
5749
os.system("wget https://raw.githubusercontent.com/pymc-devs/pymc-examples/main/examples/references.bib -P examples")
5850

5951
# bibtex config
60-
bibtex_bibfiles = ["references.bib"]
52+
bibtex_bibfiles = ["examples/references.bib"]
6153
bibtex_default_style = "unsrt"
6254
bibtex_reference_style = "author_year"
6355

64-
nbsphinx_execute = "never"
65-
66-
# Add any paths that contain templates here, relative to this directory.
67-
# templates_path = ["_templates"]
68-
69-
# The suffix(es) of source filenames.
70-
# You can specify multiple suffix as a list of string:
71-
#
72-
source_suffix = ['.rst', '.md']
73-
74-
# The master toctree document.
75-
master_doc = "index"
76-
77-
# The language for content autogenerated by Sphinx. Refer to documentation
78-
# for a list of supported languages.
79-
#
80-
# This is also used if you do content translation via gettext catalogs.
81-
# Usually you set "language" from the command line for these cases.
82-
language = None
83-
84-
# List of patterns, relative to source directory, that match files and
85-
# directories to ignore when looking for source files.
86-
# This pattern also affects html_static_path and html_extra_path.
87-
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
88-
89-
# The name of the Pygments (syntax highlighting) style to use.
90-
pygments_style = "sphinx"
91-
92-
9356
# -- Options for HTML output -------------------------------------------------
9457

9558
# The theme to use for HTML and HTML Help pages. See the documentation for
9659
# a list of builtin themes.
97-
#
98-
html_theme = "pydata_sphinx_theme"
99-
100-
# Theme options are theme-specific and customize the look and feel of a theme
101-
# further. For a list of options available for each theme, see the
102-
# documentation.
103-
104-
# https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html#remove-the-sidebar-from-some-pages
10560

61+
# theme options
62+
html_theme = "pymc_sphinx_theme"
10663
html_theme_options = {
107-
"collapse_navigation": True,
108-
"show_toc_level": 2,
109-
"navigation_depth": 4,
110-
"search_bar_text": "Search the docs...",
111-
"icon_links": [
112-
{
113-
"name": "GitHub",
114-
"url": "https://github.com/pymc-devs/pymc-bart",
115-
"icon": "fab fa-github-square",
116-
},
117-
],
64+
"secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink", "donate"],
65+
"navbar_start": ["navbar-logo"],
66+
}
67+
version = os.environ.get("READTHEDOCS_VERSION", "")
68+
version = version if "." in version else "main"
69+
html_context = {
70+
"github_url": "https://github.com",
71+
"github_user": "pymc-devs",
72+
"github_repo": "pymc-bart",
73+
"github_version": version,
74+
"default_mode": "light",
11875
}
11976

77+
78+
html_favicon = "../_static/PyMC.ico"
79+
html_logo = "../_static/PyMC.png"
80+
html_title = "PyMC-BART"
81+
12082
# Add any paths that contain custom static files (such as style sheets) here,
12183
# relative to this directory. They are copied after the builtin static files,
12284
# so a file named "default.css" will overwrite the builtin "default.css".
123-
html_static_path = ["_static"]
124-
125-
# -- Options for HTMLHelp output ---------------------------------------------
126-
127-
# Output file base name for HTML help builder.
128-
htmlhelp_basename = "pymc_bartdoc"
129-
130-
131-
# -- Options for LaTeX output ------------------------------------------------
132-
133-
latex_elements = {
134-
# The paper size ('letterpaper' or 'a4paper').
135-
#
136-
# 'papersize': 'letterpaper',
137-
# The font size ('10pt', '11pt' or '12pt').
138-
#
139-
# 'pointsize': '10pt',
140-
# Additional stuff for the LaTeX preamble.
141-
#
142-
# 'preamble': '',
143-
# Latex figure (float) alignment
144-
#
145-
# 'figure_align': 'htbp',
85+
html_static_path = ["../_static"]
86+
html_extra_path = ["../_thumbnails"]
87+
templates_path = ["../_templates"]
88+
html_sidebars = {
89+
"**": [
90+
"sidebar-nav-bs.html",
91+
],
14692
}
14793

148-
# Grouping the document tree into LaTeX files. List of tuples
149-
# (source start file, target name, title,
150-
# author, documentclass [howto, manual, or own class]).
151-
latex_documents = [
152-
(master_doc, "pymc_bart.tex", "pymc_bart Documentation", "The developers of pymc_bart", "manual"),
153-
]
154-
155-
156-
# -- Options for manual page output ------------------------------------------
157-
158-
# One entry per manual page. List of tuples
159-
# (source start file, name, description, authors, manual section).
160-
man_pages = [(master_doc, "pymc_bart", "pymc_bart Documentation", [author], 1)]
161-
162-
163-
# -- Options for Texinfo output ----------------------------------------------
164-
165-
# Grouping the document tree into Texinfo files. List of tuples
166-
# (source start file, target name, title, author,
167-
# dir menu entry, description, category)
168-
texinfo_documents = [
169-
(
170-
master_doc,
171-
"pymc_bart",
172-
"pymc_bart Documentation",
173-
author,
174-
"pymc_bart",
175-
"One line description of project.",
176-
"Miscellaneous",
177-
),
94+
# MyST config
95+
myst_enable_extensions = ["colon_fence", "deflist", "dollarmath", "amsmath", "substitution"]
96+
citation_code = f"""
97+
```bibtex
98+
@incollection{{citekey,
99+
author = "<notebook authors, see above>",
100+
title = "<notebook title>",
101+
editor = "PyMC Team",
102+
booktitle = "PyMC examples",
103+
}}
104+
```
105+
"""
106+
107+
108+
myst_substitutions = {
109+
"pip_dependencies": "{{ extra_dependencies }}",
110+
"conda_dependencies": "{{ extra_dependencies }}",
111+
"extra_install_notes": "",
112+
"citation_code": citation_code,
113+
}
114+
nb_execution_mode = "off"
115+
116+
117+
remove_from_toctrees = [
118+
"BART/*",
119+
"case_studies/*",
120+
"causal_inference/*",
121+
"diagnostics_and_criticism/*",
122+
"gaussian_processes/*",
123+
"generalized_linear_models/*",
124+
"mixture_models/*",
125+
"ode_models/*",
126+
"howto/*",
127+
"samplers/*",
128+
"splines/*",
129+
"survival_analysis/*",
130+
"time_series/*",
131+
"variational_inference/*",
178132
]
179133

134+
# bibtex config
135+
bibtex_bibfiles = ["references.bib"]
136+
bibtex_default_style = "unsrt"
137+
bibtex_reference_style = "author_year"
180138

181-
# -- Options for Epub output -------------------------------------------------
182-
183-
# Bibliographic Dublin Core info.
184-
epub_title = project
185-
186-
# The unique identifier of the text. This can be a ISBN number
187-
# or the project homepage.
188-
#
189-
# epub_identifier = ''
190-
191-
# A unique identification for the text.
192-
#
193-
# epub_uid = ''
194-
195-
# A list of files that should not be packed into the epub file.
196-
epub_exclude_files = ["search.html"]
197-
198-
199-
# -- Extension configuration -------------------------------------------------
200-
# https://svn.python.org/projects/external/Jinja-1.1/docs/build/designerdoc.html
139+
# OpenGraph config
140+
# use default readthedocs integration aka no config here
141+
142+
codeautolink_autodoc_inject = False
143+
codeautolink_concat_default = True
144+
145+
# intersphinx mappings
146+
intersphinx_mapping = {
147+
"arviz": ("https://python.arviz.org/en/latest/", None),
148+
"bambi": ("https://bambinos.github.io/bambi", None),
149+
"einstats": ("https://einstats.python.arviz.org/en/latest/", None),
150+
"mpl": ("https://matplotlib.org/", None),
151+
"numpy": ("https://numpy.org/doc/stable/", None),
152+
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
153+
"pymc": ("https://www.pymc.io/projects/docs/en/stable/", None),
154+
"pytensor": ("https://pytensor.readthedocs.io/en/latest/", None),
155+
"pmx": ("https://www.pymc.io/projects/experimental/en/latest/", None),
156+
"scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
157+
"xarray": ("https://docs.xarray.dev/en/stable/", None),
158+
}

‎docs/examples.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Examples
2+
********
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
examples/BART_introduction
8+
examples/BART_quantile_regression
9+
examples/bart_heteroscedasticity

‎docs/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ Contents
8282
.. toctree::
8383
:maxdepth: 2
8484

85-
examples/BART_introduction
85+
examples
8686
api_reference
8787

8888
Indices

‎requirements-docs.txt

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1-
nbsphinx>=0.4.2
2-
pydata-sphinx-theme>=0.6.3
3-
sphinx==5.3.0
1+
myst-nb
2+
sphinx==5.0.2 # see https://github.com/pymc-devs/pymc-examples/issues/409
3+
git+https://github.com/pymc-devs/pymc-sphinx-theme
4+
sphinxcontrib-bibtex
5+
nbsphinx
6+
sphinx_design
7+
sphinx_codeautolink
8+
sphinx_remove_toctrees

‎requirements.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
pymc>=5.0.0
22
arviz
33
numba
4-
matplotlib<=3.5.2
4+
matplotlib

0 commit comments

Comments
 (0)