example-fgen-basic/mkdocs.yml at main · openscm/example-fgen-basic · GitHub

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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
site_name: Example fgen - basic
site_description: Basic example of using fgen
site_url: https://example-fgen-basic.readthedocs.io
edit_uri: blob/master/docs/

repo_name: openscm/example-fgen-basic
repo_url: https://github.com/openscm/example-fgen-basic

theme:
  name: "material"
  features:
    - content.code.copy
  palette:
    # Light mode (toggle to dark mode)
    - scheme: default
      # Other colour choices at https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette
      primary: blue-grey
      # More info on toggles at https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle
      toggle:
        icon: material/weather-night
        name: Switch to dark mode

    # Dark mode (toggle back to light mode)
    - scheme: slate
      primary: pink
      toggle:
        icon: material/brightness-7
        name: Switch to light mode

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
        - docs/gen_fortran_api.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: ["*.py"]
      execute: true
      # Toggle off for faster builds
      # execute: false
      allow_errors: false
      # theme: dark
      include_source: True
      ignore: ["*.ipynb", "*.md", "docs/gen_doc_stubs.py", "docs/gen_fortran_api.py"]
      remove_tag_config:
        remove_input_tags:
          - remove_input
  # Docstring generation
  - mkdocstrings:
      # See https://analog-garage.github.io/mkdocstrings-python-xref/1.6.0/
      default_handler: python_xref
      enable_inventory: true
      handlers:
        python_xref:
          paths: [src]
          inventories:
            # Cross-ref helpers (lots included here, remove what you don't want)
            - https://www.attrs.org/en/stable/objects.inv
            - https://unidata.github.io/cftime/objects.inv
            - https://ipython.readthedocs.io/en/stable/objects.inv
            - https://loguru.readthedocs.io/en/latest/objects.inv
            - https://matplotlib.org/stable/objects.inv
            - https://ncdata.readthedocs.io/en/stable/objects.inv
            - https://numpy.org/doc/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://scitools-iris.readthedocs.io/en/stable/objects.inv
            - https://scmdata.readthedocs.io/en/stable/objects.inv
            # # Not available for tqdm
            # # https://github.com/tqdm/tqdm/issues/705
            # - https://tqdm.github.io/objects.inv
            - https://validators.readthedocs.io/en/stable/objects.inv
            - http://xarray.pydata.org/en/stable/objects.inv
          options:
            # It turns out that xref does this check without considering config.
            # As a result, every docstring is parsed as a google-style docstring.
            # As docstrings are only parsed once, this results in rendering failures.
            # Hence, turn off the checks here.
            # mkdocs_autorefs catches anything which doesn't end up being a correct reference.
            # The fix might be as simple as changing
            # `self.collect(ref, PythonOptions())`
            # to `self.collect(ref, self.get_options({}))`
            # in the python-xref source, but it's hard to predict the side effects
            # so we haven't bothered with that route.
            check_crossrefs: false
            docstring_style: numpy
            relative_crossrefs: true
            separate_signature: true
            show_root_heading: false
            show_signature_annotations: true
            show_source: true
            signature_crossrefs: true
            summary:
              attributes: true
              classes: true
              functions: true
              modules: true
  # https://squidfunk.github.io/mkdocs-material/plugins/search/
  - search
  # Add clickable sections to the sidebar
  # https://oprypin.github.io/mkdocs-section-index/
  - section-index

markdown_extensions:
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#attribute-lists
  - attr_list
  - footnotes
  # https://squidfunk.github.io/mkdocs-material/reference/math/#katex-mkdocsyml
  - pymdownx.arithmatex:
      generic: true
  # 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: "#"

extra_javascript:
  - javascripts/katex.js
  - https://unpkg.com/katex@0/dist/katex.min.js
  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js

extra_css:
  - https://unpkg.com/katex@0/dist/katex.min.css

watch:
  - README.md
  # Auto-generate if `src` changes (because this changes API docs)
  - src