Switch to MkDocs (#664)

* remind users they may need to scroll to see MBL version in compatibility matrix

* remove `update_schemas` script

* initial changes to text

* change dependencies to use mkdocs for documentation

* config file for mkdocs

* ignore intermediate schema conversion files for docs site

* rename sys-param schema file to be more descriptive

* improve release & docs documentation

* re-organize dev dependencies

* new mkdocs version of documentation, removing rst

* GHA workflow to deploy docs

* add link to docs site at top of readme

* remove sphinx docs build from CI

* rename overview doc file for intuitive nav

* put authors file into a markdown table

* Pre-commit and format markdown (#682)

* initial formatting

* fix issues, general cleanup

* un-indent code blocks, fix changelog header

* e.g., and i.e.,

---------

Co-authored-by: Nicholas Long <[email protected]>
Co-authored-by: Nicholas Long <[email protected]>

.coveragerc

@@ -8,7 +8,6 @@ source =
 
 [report]
 omit =
-    management/update_schemas.py
     management/check_sys_params.py
     geojson_modelica_translator/model_connectors/load_connectors/templates/RunSpawnCouplingBuilding.most
     geojson_modelica_translator/modelica/lib/runner/__init__.py

.cspell.json

@@ -2,9 +2,12 @@
   "version": "0.2",
   "language": "en",
   "words": [
+    "ambr",
     "armhf",
     "autoload",
+    "blackbox",
     "borefield",
+    "buildingslibrary",
     "buildingspy",
     "buildx",
     "Combi",
@@ -19,31 +22,47 @@
     "HVAC",
     "IBPSA",
     "interconnectivity",
+    "IWEC",
     "Jing",
     "levelname",
     "libfortran",
     "linecount",
+    "markdownlint",
+    "massflow",
     "maxdepth",
     "mfrt",
     "microgrid",
+    "miniconda",
+    "mkdocs",
+    "mkdocstrings",
     "Modelica",
     "MODELICAPATH",
     "mofile",
+    "mopt",
     "nllong",
     "nrel",
     "openstudio",
     "Optimica",
     "oversizing",
+    "pycache",
+    "pyenv",
+    "pylint",
+    "pyproject",
+    "pytest",
     "redeclarations",
     "Reparse",
+    "searchpath",
     "setpoint",
     "tanushree",
     "Templatized",
     "timeseries",
     "timestep",
     "timesteps",
     "urbanopt",
-    "vtnate"
+    "venv",
+    "virtualenv",
+    "vtnate",
+    "weatherfile"
   ],
   "flagWords": [
     "hte"

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,9 @@
 #### Any background context you want to provide?
+
 #### What does this PR accomplish?
+
 #### How should this be manually tested?
+
 #### What are the relevant tickets?
+
 #### Screenshots (if appropriate)

.github/workflows/ci.yml

@@ -18,15 +18,12 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest]
         python-version: ["3.10", "3.13"]
-        test_env: [python, docs, mypy]
+        test_env: [python, mypy]
         mbl_tag: [v11.0.0]
         exclude:
           # only test mypy on linux for all versions of python
           - os: windows-latest
             test_env: mypy
-          # only test docs on linux for all versions of python
-          - os: windows-latest
-            test_env: docs
     runs-on: ${{ matrix.os }}
     permissions: write-all
     steps:
@@ -85,12 +82,6 @@ jobs:
       - name: Run mypy
         if: matrix.test_env =='mypy'
         run: poetry run mypy --install-types --non-interactive --show-error-codes .
-      - name: Build docs
-        if: matrix.test_env == 'docs'
-        run: |
-          cd docs
-          pip install setuptools
-          poetry run make html
       - name: Coveralls
         env:
           COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}

.github/workflows/documentation_site.yml

@@ -0,0 +1,37 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-schema-reader mkdocstrings-python markdown-include
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -76,6 +76,9 @@ instance/
 docs/_build/
 docs/_autosummary/
 
+# MkDocs documentation
+/site
+
 # PyBuilder
 target/
 

.markdownlint.json

@@ -0,0 +1,9 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD003": {
+    "style": "atx"
+  },
+  "MD041": false,
+  "MD024": false
+}

.pre-commit-config.yaml

@@ -44,11 +44,22 @@ repos:
         pass_filenames: false
   # https://docs.astral.sh/ruff/integrations/#pre-commit
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.9
+    rev: v0.8.3
     hooks:
       # Run the linter
       - id: ruff
       #  unsafe fixes: https://docs.astral.sh/ruff/linter/#fixes
         args: [--fix, --exit-non-zero-on-fix, --output-format=full, --unsafe-fixes]
       # Run the formatter
       - id: ruff-format
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.43.0
+    hooks:
+      - id: markdownlint
+        name: markdownlint
+        entry: markdownlint --fix
+        language: node
+        types: [markdown]
+        args: [
+          "--config", ".markdownlint.json"
+        ]

AUTHORS.md

@@ -1,13 +1,15 @@
 # Contributors
 
-- Nicholas Long, NREL - [GitHub Profile](https://github.com/nllong)
-- Nathan Moore, NREL - [GitHub Profile](https://github.com/vtnate)
-- Ted Summer, Formerly Devetry/DEPT - [GitHub Profile](https://github.com/macintoshpie)
-- Katherine Fleming, NREL - [GitHub Profile](https://github.com/kflemin)
-- Amy Allen, NREL - [GitHub Profile](https://github.com/amyeallen1)
-- Jiazhen Ling, NREL - [GitHub Profile](https://github.com/jiazhenling)
-- Tanushree Charan, NREL - [GitHub Profile](https://github.com/tanushree04)
-- Jing Wang, NREL / CU Boulder - [GitHub Profile](https://github.com/JingWang-CUB)
-- Antoine Gautier, LBNL - [GitHub Profile](https://github.com/AntoineGautier)
-- Hagar Elarga, NREL - [GitHub Profile](https://github.com/helarga)
-- Yanfei Li, NREL - [GitHub Profile](https://github.com/YanfeiNREL)
+| Author            | Author's org          | GitHub Profile                                      |
+|:-----------------:|:---------------------:|:---------------------------------------------------:|
+| Nicholas Long     | NREL                  | [nllong](https://github.com/nllong)                 |
+| Nathan Moore      | NREL                  | [vtnate](https://github.com/vtnate)                 |
+| Ted Summer        | Formerly Devetry/DEPT | [macintoshpie](https://github.com/macintoshpie)     |
+| Katherine Fleming | NREL                  | [kflemin](https://github.com/kflemin)               |
+| Amy Allen         | NREL                  | [amyeallen1](https://github.com/amyeallen1)         |
+| Jiazhen Ling      | NREL                  | [jiazhenling](https://github.com/jiazhenling)       |
+| Tanushree Charan  | NREL                  | [tanushree04](https://github.com/tanushree04)       |
+| Jing Wang         | NREL / CU Boulder     | [JingWang-CUB](https://github.com/JingWang-CUB)     |
+| Antoine Gautier   | LBNL                  | [AntoineGautier](https://github.com/AntoineGautier) |
+| Hagar Elarga      | NREL                  | [helarga](https://github.com/helarga)               |
+| Yanfei Li         | NREL                  | [YanfeiNREL](https://github.com/YanfeiNREL)         |