From 9030ac7b8f2c849fe6eb7b9f862415127c3b1e6e Mon Sep 17 00:00:00 2001 From: f-PLT Date: Mon, 13 Apr 2026 17:07:04 -0400 Subject: [PATCH] Refactor to Properdocs --- .github/workflows/publish-gh-pages.yml | 4 ++-- .make/docs.make | 6 +++--- .make/uv.make | 2 +- docs/{mkdocs => properdocs}/css/extra.css | 0 docs/{mkdocs => properdocs}/index.md | 0 docs/{mkdocs => properdocs}/scripts/gen_ref_pages.py | 2 +- .../sections/dev-guide/developer-guide.md | 0 .../sections/user-guide/notebook-examples.md | 1 + .../sections/user-guide/user-guide.md | 0 mkdocs.yml => properdocs.yml | 10 ++++++---- pyproject.toml | 2 +- uv.lock | 6 +++--- 12 files changed, 18 insertions(+), 15 deletions(-) rename docs/{mkdocs => properdocs}/css/extra.css (100%) rename docs/{mkdocs => properdocs}/index.md (100%) rename docs/{mkdocs => properdocs}/scripts/gen_ref_pages.py (97%) rename docs/{mkdocs => properdocs}/sections/dev-guide/developer-guide.md (100%) rename docs/{mkdocs => properdocs}/sections/user-guide/notebook-examples.md (69%) rename docs/{mkdocs => properdocs}/sections/user-guide/user-guide.md (100%) rename mkdocs.yml => properdocs.yml (90%) diff --git a/.github/workflows/publish-gh-pages.yml b/.github/workflows/publish-gh-pages.yml index bb1fb35..27ced1f 100644 --- a/.github/workflows/publish-gh-pages.yml +++ b/.github/workflows/publish-gh-pages.yml @@ -46,8 +46,8 @@ jobs: make install-dev make install-docs - - name: Run mkdocs deploy + - name: Run properdocs deploy run: | - uv run mkdocs gh-deploy + uv run properdocs gh-deploy env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.make/docs.make b/.make/docs.make index 9da5248..d505d88 100644 --- a/.make/docs.make +++ b/.make/docs.make @@ -1,12 +1,12 @@ ## -- Docs targets -------------------------------------------------------------------------------------------------- ## .PHONY: preview-docs preview-docs: install-docs ## Preview the documentation site locally - @$(ENV_COMMAND_TOOL) mkdocs serve -a 0.0.0.0:7000 + @$(ENV_COMMAND_TOOL) properdocs serve -a 127.0.0.1:7000 .PHONY: build-docs build-docs: install-docs ## Build the documentation files locally - @$(ENV_COMMAND_TOOL) mkdocs build + @$(ENV_COMMAND_TOOL) properdocs build .PHONY: deploy-docs deploy-docs: install-docs ## Publish and deploy the documentation to the live Github page @@ -18,7 +18,7 @@ deploy-docs: install-docs ## Publish and deploy the documentation to the live Gi case $$ans in \ [Yy]*) \ echo""; \ - $(ENV_COMMAND_TOOL) mkdocs gh-deploy; \ + $(ENV_COMMAND_TOOL) properdocs gh-deploy; \ echo""; \ ;; \ *) \ diff --git a/.make/uv.make b/.make/uv.make index 9225267..12d2f21 100644 --- a/.make/uv.make +++ b/.make/uv.make @@ -264,7 +264,7 @@ install-jupyterlab: uv-install-auto ## Install Jupyter Lab dependencies @make -s _remind-env-activate .PHONY: install-docs -install-docs: uv-install-auto ## Install docs related dependencies (mkdocs) +install-docs: uv-install-auto ## Install docs related dependencies (properdocs) @$(ENV_INSTALL_TOOL) --extra docs --all-packages @make -s _remind-env-activate diff --git a/docs/mkdocs/css/extra.css b/docs/properdocs/css/extra.css similarity index 100% rename from docs/mkdocs/css/extra.css rename to docs/properdocs/css/extra.css diff --git a/docs/mkdocs/index.md b/docs/properdocs/index.md similarity index 100% rename from docs/mkdocs/index.md rename to docs/properdocs/index.md diff --git a/docs/mkdocs/scripts/gen_ref_pages.py b/docs/properdocs/scripts/gen_ref_pages.py similarity index 97% rename from docs/mkdocs/scripts/gen_ref_pages.py rename to docs/properdocs/scripts/gen_ref_pages.py index 6760787..94508b8 100644 --- a/docs/mkdocs/scripts/gen_ref_pages.py +++ b/docs/properdocs/scripts/gen_ref_pages.py @@ -7,7 +7,7 @@ nav = mkdocs_gen_files.Nav() root = Path(__file__).parent.parent.parent.parent -src = root / "geospatial_tools" +src = root / "src" for path in sorted(src.rglob("*.py")): module_path = path.relative_to(src).with_suffix("") diff --git a/docs/mkdocs/sections/dev-guide/developer-guide.md b/docs/properdocs/sections/dev-guide/developer-guide.md similarity index 100% rename from docs/mkdocs/sections/dev-guide/developer-guide.md rename to docs/properdocs/sections/dev-guide/developer-guide.md diff --git a/docs/mkdocs/sections/user-guide/notebook-examples.md b/docs/properdocs/sections/user-guide/notebook-examples.md similarity index 69% rename from docs/mkdocs/sections/user-guide/notebook-examples.md rename to docs/properdocs/sections/user-guide/notebook-examples.md index 353134c..7d85b52 100644 --- a/docs/mkdocs/sections/user-guide/notebook-examples.md +++ b/docs/properdocs/sections/user-guide/notebook-examples.md @@ -4,3 +4,4 @@ There are a few notebook examples available. - [How to use STAC API](https://github.com/RolnickLab/geospatial-tools/blob/main/notebooks/stac_api_tools.ipynb) - [Exploring Sentinel 2 data from Planetary Computer](https://github.com/RolnickLab/geospatial-tools/blob/main/notebooks/planetary_computer_sentinel2_exploration.ipynb) +- [Exploring Sentinel 2 data from Copernicus](https://github.com/RolnickLab/geospatial-tools/blob/main/notebooks/copernicus_sentinel2_exploration.ipynb) diff --git a/docs/mkdocs/sections/user-guide/user-guide.md b/docs/properdocs/sections/user-guide/user-guide.md similarity index 100% rename from docs/mkdocs/sections/user-guide/user-guide.md rename to docs/properdocs/sections/user-guide/user-guide.md diff --git a/mkdocs.yml b/properdocs.yml similarity index 90% rename from mkdocs.yml rename to properdocs.yml index 847b9bc..0c06488 100644 --- a/mkdocs.yml +++ b/properdocs.yml @@ -2,7 +2,7 @@ site_name: Geospatial Tools site_description: A package contain classes and utilities to help with geospatial data repo_url: https://github.com/RolnickLab/geospatial-tools -docs_dir: docs/mkdocs +docs_dir: docs/properdocs nav: - User Guide: - sections/user-guide/user-guide.md @@ -19,6 +19,7 @@ theme: palette: - media: "(prefers-color-scheme)" + primary: deep orange toggle: icon: material/brightness-auto name: Switch to light mode @@ -26,6 +27,7 @@ theme: # Palette toggle for light mode - media: "(prefers-color-scheme: light)" scheme: default + primary: deep orange toggle: icon: material/brightness-7 @@ -34,6 +36,7 @@ theme: # Palette toggle for dark mode - media: "(prefers-color-scheme: dark)" scheme: slate + primary: deep orange toggle: icon: material/brightness-4 name: Switch to system preference @@ -52,14 +55,14 @@ plugins: - search - gen-files: scripts: - - docs/mkdocs/scripts/gen_ref_pages.py + - docs/properdocs/scripts/gen_ref_pages.py - literate-nav - section-index - mkdocstrings: default_handler: python handlers: python: - paths: [geospatial_tools] + paths: [src] options: inherited_members: true docstring_style: google @@ -77,4 +80,3 @@ plugins: show_symbol_type_toc: true line_length: 88 merge_init_into_class: true - diff --git a/pyproject.toml b/pyproject.toml index 4389dae..97523dc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -59,12 +59,12 @@ dev = [ ] [project.optional-dependencies] docs =[ - "mkdocs>=1.6.1", "mkdocs-material>=9.6.20", "mkdocs-gen-files>=0.5.0", "mkdocs-literate-nav>=0.6.2", "mkdocs-section-index>=0.3.10", "mkdocstrings-python>=1.18.2", + "properdocs>=1.6.7", ] lab = [ "jupyterlab>=4.0.10", diff --git a/uv.lock b/uv.lock index bafcc81..22d3df4 100644 --- a/uv.lock +++ b/uv.lock @@ -1435,12 +1435,12 @@ dependencies = [ [package.optional-dependencies] docs = [ - { name = "mkdocs" }, { name = "mkdocs-gen-files" }, { name = "mkdocs-literate-nav" }, { name = "mkdocs-material" }, { name = "mkdocs-section-index" }, { name = "mkdocstrings-python" }, + { name = "properdocs" }, ] lab = [ { name = "jupyterlab" }, @@ -1482,7 +1482,6 @@ requires-dist = [ { name = "jupyterlab-lsp", marker = "extra == 'lab'", specifier = ">=5.0.1" }, { name = "leafmap", specifier = ">=0.31.9" }, { name = "localtileserver", specifier = ">=0.11.0" }, - { name = "mkdocs", marker = "extra == 'docs'", specifier = ">=1.6.1" }, { name = "mkdocs-gen-files", marker = "extra == 'docs'", specifier = ">=0.5.0" }, { name = "mkdocs-literate-nav", marker = "extra == 'docs'", specifier = ">=0.6.2" }, { name = "mkdocs-material", marker = "extra == 'docs'", specifier = ">=9.6.20" }, @@ -1493,6 +1492,7 @@ requires-dist = [ { name = "pandas", specifier = ">=2.2.2" }, { name = "pillow", specifier = ">=11.3.0" }, { name = "planetary-computer", specifier = ">=1.0.0" }, + { name = "properdocs", marker = "extra == 'docs'", specifier = ">=1.6.7" }, { name = "pyarrow", specifier = ">=17.0.0" }, { name = "pyogrio", specifier = ">=0.8.0" }, { name = "pystac-client", specifier = ">=0.7.7" }, @@ -1619,7 +1619,7 @@ name = "importlib-metadata" version = "9.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ - { name = "zipp" }, + { name = "zipp", marker = "python_full_version < '3.12'" }, ] sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" } wheels = [