1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
site_name: RSCM
site_description: Simple Climate Model built in Rust
site_url: https://lewisjared.github.io/rscm
edit_uri: blob/master/docs/
repo_name: lewisjared/rscm
repo_url: https://github.com/lewisjared/rcsm
theme:
name: "material"
features:
- content.code.copy
custom_dir: docs/overrides
palette:
# Light mode (toggle to dark mode)
- scheme: cr-light
primary: teal
accent: cyan
toggle:
icon: material/weather-night
name: Switch to dark mode
# Dark mode (toggle back to light mode)
- scheme: cr-dark
primary: teal
accent: cyan
toggle:
icon: material/brightness-7
name: Switch to light mode
# Enable versioned doc builds
# Using {major}.{minor}, latest and dev releases
extra:
version:
provider: mike
extra_css:
- stylesheets/style.css
plugins:
# https://mkdocstrings.github.io/autorefs/
- autorefs
# Required for auto-generating our documentation stubs
# https://oprypin.github.io/mkdocs-gen-files/
- gen-files:
scripts:
- docs/gen_doc_stubs.py
# Make the navigation easier to handle/auto-generate if we wish
# https://oprypin.github.io/mkdocs-literate-nav/
- literate-nav:
nav_file: NAVIGATION.md
# Notebook support.
# Working out how to make this play with nb-exec would be nice,
# then it wouldn't run every time.
# See also: https://github.com/danielfrg/mkdocs-jupyter/issues/161
# We could also get the nb-exec-table mentioned here:
# https://myst-nb.readthedocs.io/en/v0.12.2/use/execute.html
# One for another day.
- mkdocs-jupyter:
# Use filenames for titles
ignore_h1_titles: True
include:
execute: true
# Toggle off for faster builds
# execute: false
allow_errors: false
# theme: dark
include_source: True
ignore:
remove_tag_config:
remove_input_tags:
- remove_input
# Docstring generation
- mkdocstrings:
enable_inventory: true
handlers:
python:
paths:
import:
# Cross-ref helpers (lots included here, remove what you don't want)
- https://www.attrs.org/en/stable/objects.inv
- https://ipython.readthedocs.io/en/stable/objects.inv
- https://matplotlib.org/stable/objects.inv
- https://openscm-units.readthedocs.io/en/stable/objects.inv
- https://pandas.pydata.org/docs/objects.inv
- https://pint.readthedocs.io/en/stable/objects.inv
- https://www.fatiando.org/pooch/latest/objects.inv
- https://docs.python.org/3/objects.inv
- https://docs.scipy.org/doc/scipy/objects.inv
- https://scmdata.readthedocs.io/en/stable/objects.inv
options:
docstring_style: numpy
show_root_heading: true
show_source: true
# https://squidfunk.github.io/mkdocs-material/plugins/search/
- search
# https://oprypin.github.io/mkdocs-section-index/
- section-index
# https://github.com/byrnereese/mkdocs-minify-plugin
- minify:
minify_html: true
minify_js: true
minify_css: true
# https://github.com/jimporter/mike
- mike:
alias_type: copy
markdown_extensions:
# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#attribute-lists
- attr_list
# Allow admonitions, useful for deprecation warnings
# https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/admonition/
- pymdownx.blocks.admonition
# Code highlighting handiness
# https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
# https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
- pymdownx.inlinehilite
# Enable the use of snippets (e.g. taking snippets from README and putting them in docs)
# https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
- pymdownx.snippets
# Support more complicated indents etc.
# https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
- pymdownx.superfences
# Tabbed sections (e.g. for our installation options)
# https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
- pymdownx.tabbed:
alternate_style: true
# Support tables (used in our API docs)
# https://squidfunk.github.io/mkdocs-material/reference/data-tables/
- tables
# Ensure that there are links to table of contents items
- toc:
permalink: "#"
watch:
- README.md
# Auto-generate if `python` changes (because this changes API docs)
- python