portpy.github.io/mkdocs.yml at main · PortPy-Project/portpy.github.io · 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

# MkDocs configuration file for the PortPy documentation site.
# This file defines the site title, theme, navigation structure, plugins, and custom styling/scripts.
# It uses the Material for MkDocs theme and includes pages for user guides, tutorials, API reference, and more.

# ----  Site metadata shown in the browser and used for SEO --------

#site_name: PortPy
site_name: ""
site_description: Open-source Python library for radiation therapy planning and optimization.
site_author: PortPy Contributors
repo_url: https://github.com/PortPy-Project/PortPy  # Link to the GitHub repository (shown in top-right corner)
repo_name: PortPy on GitHub

# ---- Theme and appearance settings using Material for MkDocs --------

theme:
  name: material
  logo: images/PortPy_logo.png                      # Logo shown in the navigation bar
  favicon: images/PortPy_logo.png                   # Icon shown in browser tabs
  palette:                                          # Define light and dark color schemes
    - scheme: default
      primary: "#4051b5"
      accent: "#009688"
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    - scheme: slate
      primary: teal
      accent: lime
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode

  # Set fonts for text and code
  font:
    text: Roboto
    code: Roboto Mono
  features:
#    - navigation.expand
    - navigation.instant                              # Instantly loads new pages without full reload
    #- navigation.tabs                                 # Displays top-level navigation as horizontal tabs
    - navigation.top                                  # Keeps the top navigation bar visible while scrolling (sticky header)
    #- toc.integrate                                   # Integrates table of contents into the side navigation
    - search.suggest                                  # Suggests search terms as you type
    - search.highlight                                # Highlights search terms in the results

    - content.code.annotate                       # works with the pymdownx.inlinehilite and pymdownx.snippets extensions.
                                                  # It allows highlighting specific parts of code and provides explanations inline using custom syntax.(like ==highlight== or --comment-- formats)
    - content.code.copy                           # Adds a copy button to code blocks for easy copying


# --------Navigation structure for the sidebar and top menu --------

nav:
  - Home: index.md
  - Quick Start: quick_start.md
  - FAQ: FAQ.md
  - Contact Us: contact_us.md
  - Resources: resources.md
#  - Tutorials:
#      - Introduction: tutorials/introduction.md
#      - Data Loading: tutorials/data_loading.md
#      - Plan Optimization: tutorials/plan_optimization.md
#      - Plan Evaluation: tutorials/plan_evaluation.md
#      - Global Optimization: tutorials/global_optimization.md
#      - TPS Integration: tutorials/tps_integration.md
#  #- Benchmark Datasets: benchmark_datasets.md
#  - Extensions:
#      - Overview: extensions/overview.md
#      - CompressRTP: extensions/compressRTP.md
#      - ECHO-VMAT: extensions/echo_vmat.md


# --------MkDocs plugins used to enhance functionality --------

plugins:
  - search                                              # Adds search functionality
  - mkdocstrings:                                       # Automatically builds API documentation from Python docstrings in the 'portpy' package
      handlers:
        python:
          paths: [portpy]                               # Specify the path to the Python package for API documentation
  - awesome-pages                                       # Allows for easy creation of a multi-level navigation structure with .pages files
  - minify                                              # Minifies HTML, CSS, and JavaScript files for faster loading
  - mermaid2                                            # Enables rendering of Mermaid diagrams in Markdown files
  - mkdocs-jupyter                                      # Allows for embedding Jupyter notebooks in Markdown files
 # - mike                                                # Used for versioning the documentation
  - tags                                                # Adds support for tagging pages in the documentation

# ---- Markdown Extensions ----

markdown_extensions:                                    # Adds features to Markdown rendering
  - admonition                                          # Enables note, warning, and tip blocks
  - codehilite                                          # Syntax highlighting for code blocks
  - footnotes                                           # Enables footnotes in Markdown
  - toc:                                                # Table of contents settings
      permalink: true
      toc_depth: 2
  - pymdownx.superfences                                # Enables nested code blocks
  - pymdownx.highlight                                  # Syntax highlighting for code blocks
  - pymdownx.details                                    # Expandable details blocks
  - pymdownx.tabbed:                                     # Tabbed content blocks
     alternate_style: true
  - pymdownx.arithmatex:
     inline_syntax: ['dollar']


# -------- Extra Site Settings --------

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/PortPy-Project/PortPy
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/portpy-photon/
  arithmatex:
    inline: '$'
    block: '$$'

extra_javascript: # Include custom JavaScript files
  - js/extra.js
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

extra_css: # Include custom CSS files
  - styles/extra.css