Skip to content

Commit 588a94a

Browse files
andersy005katamartinpre-commit-ci[bot]
authored
Migrate documentation from MkDocs to Sphinx (#364)
Co-authored-by: Kata Martin <katasm@gmail.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 30441d2 commit 588a94a

31 files changed

Lines changed: 407 additions & 352 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,3 +184,4 @@ pixi.lock
184184
uv.lock
185185
environment.yaml
186186
.DS_Store
187+
_build/

‎.readthedocs.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,4 @@ build:
1818
- pixi install -e docs
1919
build:
2020
html:
21-
- pixi run -e docs mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
21+
- pixi run -e docs sphinx-build -b html docs $READTHEDOCS_OUTPUT/html

‎contributing.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -70,17 +70,21 @@ Once you have pushed your changes to your forked repository, you can submit a pu
7070

7171
## Contributing documentation
7272

73-
!Note: Directions for uv, we can update to pixi.
73+
Our documentation is built with Sphinx and deployed automatically to ReadTheDocs on every PR and merge to `main`.
7474

75-
Our documentation is built with `mkdocs`.
75+
To build and serve the docs locally:
7676

77-
To build the docs:
78-
79-
1.
77+
```bash
78+
# Build the documentation
79+
pixi run docs-build
8080

81+
# Serve the documentation locally
82+
pixi run docs-serve
8183
```
82-
uv run --group docs mkdocs serve
83-
...
8484

85-
2. Navigate to localhost:8000
86-
```
85+
Then navigate to <http://localhost:8000> to view the docs.
86+
87+
Documentation is automatically deployed:
88+
89+
- **PR previews**: Every pull request gets a preview deployment on ReadTheDocs
90+
- **Production**: Merges to `main` automatically deploy to <https://open-climate-risk.readthedocs.io/>

‎docs/access-data.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
# Access Data
1+
# Access data
22

3-
There a few different ways to access the data, in addition to exploration via the web tool. This page outlines the different versions and formats of data available for download.
3+
There a few different ways to access the data, in addition to exploration via the map tool. This page outlines the different versions and formats of data available for download.
44

5-
<!-- prettier-ignore-start -->
6-
!!! warning "License Agreement"
7-
Open Climate Risk data are made available under the licenses listed below. By accessing the data, you agree to adhere to the license terms.
5+
:::{admonition} **License Agreement**
6+
:class: warning
87

9-
<!-- prettier-ignore-end -->
8+
Open Climate Risk data are made available under the licenses listed below. By accessing the data, you agree to adhere to the license terms.
9+
:::
1010

11-
<!-- prettier-ignore-start -->
12-
!!! warning "Terms of Data Use"
13-
By viewing Open Climate Risk data, you agree to the [Terms of Data Access](terms-of-data-access.md).
11+
:::{admonition} **Terms of Data Use**
12+
:class: warning
1413

15-
<!-- prettier-ignore-end -->
14+
By viewing Open Climate Risk data, you agree to the [Terms of Data Access](terms-of-data-access.md).
15+
:::
1616

1717
## Download options
1818

@@ -21,7 +21,7 @@ There a few different ways to access the data, in addition to exploration via th
2121
| **Raster (tensor) data** | Full gridded dataset spanning CONUS | Icechunk (Zarr-based) | [Source Coop](https://source.coop/carbonplan/carbonplan-ocr) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | [K Riley et al. 2025](https://doi.org/10.2737/RDS-2025-0006), [J Scott et al. 2024](https://doi.org/10.2737/RDS-2020-0016-2), [R Rasmussen et al. 2023](https://doi.org/10.1175/BAMS-D-21-0326.1) |
2222
| **Vector (polygon) data** | Full buildings dataset spanning CONUS | GeoParquet | [Source Coop](https://source.coop/carbonplan/carbonplan-ocr) | [ODbL](https://opendatacommons.org/licenses/odbl/1-0/) | [Overture Maps Foundation buildings dataset](https://docs.overturemaps.org/guides/buildings/), [K Riley et al. 2025](https://doi.org/10.2737/RDS-2025-0006), [J Scott et al. 2024](https://doi.org/10.2737/RDS-2020-0016-2), [R Rasmussen et al. 2023](https://doi.org/10.1175/BAMS-D-21-0326.1) |
2323
| **Regional statistics** | Summary statistics for regions (state, county, census tract, census block) within CONUS | CSV, GeoJSON | [Source Coop](https://source.coop/carbonplan/carbonplan-ocr) | [ODbL](https://opendatacommons.org/licenses/odbl/1-0/) | [Census TIGER/Line](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html), [Overture Maps Foundation buildings dataset](https://docs.overturemaps.org/guides/buildings/), [K Riley et al. 2025](https://doi.org/10.2737/RDS-2025-0006), [J Scott et al. 2024](https://doi.org/10.2737/RDS-2020-0016-2), [R Rasmussen et al. 2023](https://doi.org/10.1175/BAMS-D-21-0326.1) |
24-
| **Subsetted vector (point) data** | Building-level data subsetted to active region (county, census tract, census block) | CSV, GeoPackage | Web tool (see below) | [ODbL](https://opendatacommons.org/licenses/odbl/1-0/) | [Census TIGER/Line](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html), [Overture Maps Foundation buildings dataset](https://docs.overturemaps.org/guides/buildings/), [K Riley et al. 2025](https://doi.org/10.2737/RDS-2025-0006), [J Scott et al. 2024](https://doi.org/10.2737/RDS-2020-0016-2), [R Rasmussen et al. 2023](https://doi.org/10.1175/BAMS-D-21-0326.1) |
24+
| **Subsetted vector (point) data** | Building-level data subsetted to active region (county, census tract, census block) | CSV, GeoPackage | Map tool (see below) | [ODbL](https://opendatacommons.org/licenses/odbl/1-0/) | [Census TIGER/Line](https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html), [Overture Maps Foundation buildings dataset](https://docs.overturemaps.org/guides/buildings/), [K Riley et al. 2025](https://doi.org/10.2737/RDS-2025-0006), [J Scott et al. 2024](https://doi.org/10.2737/RDS-2020-0016-2), [R Rasmussen et al. 2023](https://doi.org/10.1175/BAMS-D-21-0326.1) |
2525

2626
## Full dataset downloads
2727

@@ -76,9 +76,9 @@ The schemas for each of the full datasets are described on the [data schema](./r
7676
| `risk_score_2011_hist` | float[] | Count of buildings with each risk score (~2011 climate conditions). |
7777
| `risk_score_2047_hist` | float[] | Count of buildings with each risk score (~2047 climate conditions). |
7878

79-
## Downloading subsetted data in the web tool
79+
## Downloading subsetted data in the map tool
8080

81-
The [web tool](https://carbonplan.org/research/climate-risk) can be used to access region-specific, subsetted downloads.
81+
The [map tool](https://carbonplan.org/research/climate-risk) can be used to access region-specific, subsetted downloads.
8282

8383
### Steps
8484

@@ -87,7 +87,7 @@ The [web tool](https://carbonplan.org/research/climate-risk) can be used to acce
8787
3. Select your region of interest (continental US, state, county, census tract, or census block) and view trends inline.
8888
4. For subsetted, building-level data (schema below), click `CSV ↓` or `GeoPackage ↓` to download the applicable file for the selected region.
8989

90-
_If you are instead interested in summary statistics for the region (e.g., to reproduce the histogram), you may click `CSV ↓` or `GeoJSON ↓` to download those files (also [available above](#regional-statistics-downloads))._
90+
_If you are instead interested in summary statistics for the region (e.g., to reproduce the histogram), you may click `CSV ↓` or `GeoJSON ↓` to download those files (also available in the Regional statistics downloads section above)._
9191

9292
![](./assets/web-data-downloads.png)
9393

‎docs/assets/custom.css‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/conf.py‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
import datetime
2+
import sys
3+
4+
import ocr
5+
6+
print('python exec:', sys.executable)
7+
print('sys.path:', sys.path)
8+
9+
10+
project = 'OCR'
11+
this_year = datetime.datetime.now().year
12+
copyright = f'{this_year}, CarbonPlan'
13+
author = 'CarbonPlan'
14+
15+
release = ocr.__version__
16+
17+
# -- General configuration ---------------------------------------------------
18+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
19+
20+
extensions = [
21+
'sphinx.ext.autodoc',
22+
'sphinx.ext.viewcode',
23+
'sphinx.ext.autosummary',
24+
'sphinx.ext.doctest',
25+
'sphinx.ext.intersphinx',
26+
'sphinx.ext.extlinks',
27+
'sphinx.ext.napoleon',
28+
'sphinx.ext.mathjax',
29+
'myst_nb',
30+
'sphinxext.opengraph',
31+
'sphinx_copybutton',
32+
'sphinx_design',
33+
'sphinxcontrib.mermaid',
34+
'sphinx_click',
35+
]
36+
37+
# MyST config
38+
myst_enable_extensions = [
39+
'amsmath',
40+
'dollarmath',
41+
'colon_fence',
42+
'deflist',
43+
'html_image',
44+
'tasklist',
45+
]
46+
myst_url_schemes = ['http', 'https', 'mailto']
47+
myst_fence_as_directive = ['mermaid']
48+
myst_heading_anchors = 2
49+
50+
# sphinx-copybutton configurations
51+
copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
52+
copybutton_prompt_is_regexp = True
53+
54+
# Autodoc configuration
55+
autodoc_default_options = {
56+
'members': True,
57+
'member-order': 'bysource',
58+
'undoc-members': True,
59+
'exclude-members': '__weakref__',
60+
}
61+
autodoc_typehints = 'description'
62+
autodoc_typehints_description_target = 'documented'
63+
# Don't show private members (those starting with _)
64+
autodoc_default_flags = ['members', 'show-inheritance']
65+
66+
autosummary_generate = True
67+
68+
nb_execution_mode = 'off'
69+
nb_execution_timeout = 600
70+
nb_execution_raise_on_error = False
71+
72+
# Mermaid configuration
73+
mermaid_output_format = 'raw'
74+
mermaid_version = '11.4.0'
75+
mermaid_d3_zoom = True # Enable zoom functionality
76+
d3_version = '7.9.0' # D3 version for zoom
77+
78+
79+
# Intersphinx mapping
80+
intersphinx_mapping = {
81+
'python': ('https://docs.python.org/3/', None),
82+
'geopandas': ('https://geopandas.org/en/stable/', None),
83+
'numpy': ('https://numpy.org/doc/stable/', None),
84+
'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
85+
'xarray': ('https://docs.xarray.dev/en/stable/', None),
86+
'icechunk': ('https://icechunk.io/en/stable/', None),
87+
}
88+
89+
templates_path = ['_templates']
90+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**/.ipynb_checkpoints']
91+
source_suffix = ['.rst', '.md']
92+
93+
94+
# -- Options for HTML output -------------------------------------------------
95+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
96+
97+
html_theme = 'sphinx_book_theme'
98+
html_title = 'Open Climate Risk'
99+
html_favicon = 'assets/favicon-180x180-light.png'
100+
101+
html_theme_options = {
102+
'repository_url': 'https://github.com/carbonplan/ocr',
103+
'repository_branch': 'main',
104+
'path_to_docs': 'docs',
105+
'use_repository_button': True,
106+
'use_edit_page_button': True,
107+
'use_issues_button': True,
108+
'use_download_button': True,
109+
'use_fullscreen_button': True,
110+
'home_page_in_toc': True,
111+
'show_toc_level': 2,
112+
'logo': {
113+
'image_light': 'assets/monogram-dark-cropped.png',
114+
'image_dark': 'assets/monogram-light-cropped.png',
115+
},
116+
}
117+
118+
html_static_path = ['assets']
119+
120+
121+
# OpenGraph configuration
122+
ogp_site_url = 'https://open-climate-risk.readthedocs.io/'
123+
ogp_site_name = 'Open Climate Risk'
124+
ogp_description = (
125+
'Building-level climate risk assessments across the continental United States. '
126+
'Access fire and wind risk data, explore methodologies, and analyze climate impacts.'
127+
)
128+
ogp_type = 'website'
129+
# ogp_image = ''
130+
ogp_image_alt = 'Open Climate Risk - CarbonPlan'
131+
ogp_image_width = '1200' # Optimal for LinkedIn, Bluesky, Twitter
132+
ogp_image_height = '630' # Standard social card dimensions (1.91:1 ratio)
133+
ogp_description_length = 200
134+
ogp_enable_meta_description = True
135+
ogp_use_first_image = True # Use first image in page if available
136+
137+
# Social cards configuration - generates cards automatically
138+
ogp_social_cards = {
139+
'enable': True,
140+
}
141+
142+
# Custom meta tags for enhanced social media support
143+
# These work across Bluesky, LinkedIn, and Facebook
144+
ogp_custom_meta_tags = [
145+
# Additional metadata for better indexing
146+
'<meta property="article:author" content="CarbonPlan" />',
147+
'<meta name="author" content="CarbonPlan" />',
148+
]

‎docs/how-to/data-pipeline.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Open Climate Risk Data Pipeline
1+
# Open Climate Risk data pipeline
22

33
The Open Climate Risk (OCR) data pipeline processes climate risk data through a series of coordinated stages, from individual region processing to final tile generation for visualization.
44

@@ -129,12 +129,16 @@ ocr run --env-file .env --region-id y10_x2
129129

130130
## CLI Commands
131131

132-
<!-- prettier-ignore -->
133-
::: mkdocs-click
134-
:module: ocr.deploy.cli
135-
:command: ocr
136-
:prog_name: ocr
137-
:list_subcommands: true
132+
For detailed CLI documentation, see the [API Reference](../reference/api.md#cli-application).
133+
134+
```bash
135+
# View all available commands
136+
ocr --help
137+
138+
# View help for a specific command
139+
ocr run --help
140+
ocr aggregate-regional-stats --help
141+
```
138142

139143
### Pipeline Orchestration
140144

‎docs/how-to/developer-guide-index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Developer guides
2+
3+
These guides help you set up and contribute to the Open Climate Risk development environment.
4+
5+
```{toctree}
6+
:maxdepth: 1
7+
8+
installation
9+
data-pipeline
10+
input-dataset-ingestion
11+
work-with-input-datasets
12+
release-procedure
13+
snapshot-testing
14+
```

‎docs/how-to/getting-started.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Getting Started
1+
# Getting started
22

33
This guide helps you get started with accessing and using Open Climate Risk fire risk data for the continental United States.
44

@@ -77,9 +77,11 @@ The dataset contains several key variables:
7777
- **`crps`**: Conditional Risk to Potential Structures (damage if fire occurs)
7878
- Risk scores are for a "generic" or "potential" structure at each location
7979

80-
!!! note "Important Limitation"
80+
:::{admonition} **Important Limitation**
81+
:class: note
8182

82-
Risk scores represent a hypothetical structure and do NOT account for building-specific factors like construction materials, retrofits, or defensible space management.
83+
Risk scores represent a hypothetical structure and do NOT account for building-specific factors like construction materials, retrofits, or defensible space management.
84+
:::
8385

8486
## Next Steps
8587

‎docs/how-to/input-dataset-ingestion.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Input Dataset Ingestion
1+
# Input dataset ingestion
22

33
This guide covers how to ingest and process input datasets for the Open Climate Risk (OCR) project using the unified CLI infrastructure.
44

0 commit comments

Comments
 (0)