Skip to content

Commit 775bbda

Browse files
tomjemmetttomjemmett
authored
Merge pull request #502 from The-Strategy-Unit/add_mkdocs
adds mkdocs support
2 parents 653cce1 + 946987e commit 775bbda

6 files changed

Lines changed: 473 additions & 3 deletions

File tree

‎.github/workflows/deploy_docs.yaml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
permissions:
8+
contents: read
9+
pages: write
10+
id-token: write
11+
12+
concurrency:
13+
group: "pages"
14+
cancel-in-progress: false
15+
16+
jobs:
17+
build:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- name: Install uv
23+
uses: astral-sh/setup-uv@v6
24+
25+
- name: Set up Python
26+
run: uv python install
27+
28+
- name: Install dependencies
29+
run: uv sync --extra docs
30+
31+
- name: Build documentation
32+
run: uv run mkdocs build --clean
33+
34+
- name: Setup Pages
35+
uses: actions/configure-pages@v4
36+
37+
- name: Upload artifact
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: site
41+
path: ./site
42+
43+
deploy:
44+
runs-on: ubuntu-latest
45+
needs: build
46+
steps:
47+
- name: Download artifact
48+
uses: actions/download-artifact@v4
49+
with:
50+
name: site
51+
path: ./site
52+
53+
- name: Install uv (for rsconnect)
54+
uses: astral-sh/setup-uv@v6
55+
56+
- name: Configure Connect
57+
run: uvx rsconnect add -s ${{ secrets.RSCONNECT_URL }} -n connect -k ${{ secrets.RSCONNECT_API_KEY }}
58+
59+
- name: Deploy to Connect
60+
run: uvx rsconnect deploy html site -a ${{ vars.CONNECT_DOCS_APP_ID }}

‎docs/gen_ref_pages.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
"""Generate the code reference pages and navigation."""
2+
3+
from pathlib import Path
4+
5+
import mkdocs_gen_files
6+
7+
nav = mkdocs_gen_files.Nav()
8+
9+
src = Path(__file__).parent.parent / "src"
10+
for path in sorted(src.rglob("*.py")):
11+
module_path = path.relative_to(src).with_suffix("")
12+
doc_path = path.relative_to(src).with_suffix(".md")
13+
full_doc_path = Path("reference", doc_path)
14+
15+
parts = tuple(module_path.parts)
16+
17+
if parts[-1] == "__init__":
18+
parts = parts[:-1]
19+
doc_path = doc_path.with_name("index.md")
20+
full_doc_path = full_doc_path.with_name("index.md")
21+
elif parts[-1] == "__main__":
22+
continue
23+
24+
nav[parts] = doc_path.as_posix()
25+
26+
with mkdocs_gen_files.open(full_doc_path, "w") as fd:
27+
ident = ".".join(parts)
28+
fd.write(f"::: {ident}")
29+
30+
mkdocs_gen_files.set_edit_path(full_doc_path, path)
31+
32+
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
33+
nav_file.writelines(nav.build_literate_nav())

‎docs/index.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# NHP Model Documentation
2+
3+
Welcome to the NHP Model documentation. This project provides modeling capabilities for healthcare activity prediction.
4+
5+
## Features
6+
7+
- Multiple model types (inpatients, outpatients, A&E)
8+
- Support for loading data from different sources
9+
- Docker containerization
10+
11+
## Quick Start
12+
13+
Download and install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), then run `uv sync`. Download data locally, e.g., download a synthetic dataset to `data/synth`. Then, run the model with:
14+
15+
``` bash
16+
uv run python -m nhp.model queue/params-sample.json -d data/synth --type all
17+
```
18+
19+
## API Reference
20+
21+
See the [Model Reference](reference/nhp/model/index.md) for detailed documentation of all classes and functions.

‎mkdocs.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
site_name: NHP Model Documentation
2+
site_description: Documentation for the NHP Model project
3+
site_url: https://connect.strategyunitwm.nhs.uk/nhp/model_documentation/
4+
5+
repo_url: https://github.com/the-strategy-unit/nhp_model
6+
repo_name: the-strategy-unit/nhp_model
7+
8+
theme:
9+
name: material
10+
features:
11+
- navigation.tabs
12+
- navigation.sections
13+
- navigation.expand
14+
- navigation.top
15+
- search.highlight
16+
- content.code.copy
17+
18+
plugins:
19+
- search
20+
- gen-files:
21+
scripts:
22+
- docs/gen_ref_pages.py
23+
- literate-nav:
24+
nav_file: SUMMARY.md
25+
- section-index
26+
- mkdocstrings:
27+
handlers:
28+
python:
29+
options:
30+
docstring_style: google
31+
show_source: true
32+
show_root_heading: true
33+
show_root_toc_entry: false
34+
merge_init_into_class: true
35+
filters:
36+
- "!_version"
37+
- "!__main__"
38+
39+
nav:
40+
- Home: index.md
41+
- API Reference: reference/

‎pyproject.toml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,14 @@ databricks = [
5757
"pyspark",
5858
"databricks-connect"
5959
]
60+
docs = [
61+
"mkdocs",
62+
"mkdocs-material",
63+
"mkdocstrings[python]",
64+
"mkdocs-gen-files",
65+
"mkdocs-literate-nav",
66+
"mkdocs-section-index"
67+
]
6068

6169
[build-system]
6270
requires = ["setuptools>=80", "setuptools-scm>=8", "wheel"]
@@ -112,4 +120,4 @@ line-ending = "auto"
112120
version_file = "src/nhp/model/_version.py"
113121

114122
[tool.ty.src]
115-
exclude = ["notebooks"]
123+
exclude = ["notebooks", "docs"]

0 commit comments

Comments
 (0)