pytemplate/mkdocs.yml at main · saemeon/pytemplate · 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
site_name: mypackage
site_description: A short description of your package
site_author: Simon Niederberger
site_url: https://saemeon.github.io/mypackage/

repo_url: https://github.com/saemeon/mypackage
repo_name: saemeon/mypackage

copyright: "Copyright &copy; 2026 Simon Niederberger"

nav:
  - Overview: "index.md"
  - API: "api.md"
  - Examples: "generated/gallery"

theme:
  name: material
  # this parameter defines where to find HTML that will overwrite or complement the pages from the theme
  features:
    - content.width.wide
    # enables annotations, see https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations
    - content.code.annotate
    # add a button to copy code snippets
    - content.code.copy
    # link tabs within a page
    - content.tabs.link
    # for navigation features see https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
    - navigation.top
    - navigation.tracking
    # keep all sections in the navigation expanded by default
    # - navigation.expand
    # add icon and link to the document on gihub for each page
    - content.action.edit
    # add highlighting of search words
    - search.highlight
    # add autocomplete to the search bar
    - search.suggest
  icon:
    repo: fontawesome/brands/github
    edit: material/eye
  favicon: assets/favicon.ico
  palette:
    # light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      # definition of the  header icon for this mode
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    # dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      # definition of the  header icon for this mode
      toggle:
        icon: material/weather-night
        name: Switch to light mode

# use a long list of recommended extensions from https://squidfunk.github.io/mkdocs-material/setup/extensions/?h=pymdownx#recommended-configuration
markdown_extensions:
  # Python Markdown
  - admonition
  - toc:
      permalink: true
  # Python Markdown Extensions
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
  - pymdownx.tilde
  # tabbed content (e.g. variants of code)
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.arithmatex
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          # where to look for python modules. not strictly required, but helps, if building from an arbitrary folder
          paths: [src]
          options:
            docstring_style: numpy
            docstring_section_style: spacy
            show_if_no_docstring: False
            show_root_toc_entry: False
            show_source: False
            heading_level: 3
            # show if an element is an attribute/class or function in the headers, but not in the ToC on the right
            show_symbol_type_heading: True
            show_symbol_type_toc: False
            # merge doc of __init__ into class doc
            merge_init_into_class: True
            show_signature: True
            separate_signature: True
            # decide in the code how verbose the type hints should be
            annotations_path: source
            filters: ["!^_[^_]"]
  - mike:
      canonical_version: latest
      alias_type: redirect # symlink seems not to work out-of-the-box on expo; redirect leads to missing .../latest/... links, but seems to be ok
      # the rest of setting below are the defaults according to the `mike` docs
      redirect_template: null
      deploy_prefix: ""
      version_selector: True
      css_dir: css
      javascript_dir: js
  - gallery:
      examples_dirs: examples
      gallery_dirs: docs/generated/gallery
      within_subsection_order: FileNameSortKey
extra_javascript:
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
extra_css:
  - assets/extra.css

watch:
  - src

remote_branch: documentation

extra:
  version:
    provider: mike
    alias: true
    default: latest
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/saemeon/mypackage