Use the tool_template repo to create docs (#15)

* Use the tool_template repo to create docs Signed-off-by: Fabrice Normandin <normandf@mila.quebec> * Update the build hook Signed-off-by: Fabrice Normandin <normandf@mila.quebec> * Use `uvx pre-commit` in the linting step Signed-off-by: Fabrice Normandin <normandf@mila.quebec> * Fix for broken docformatter hook - PyCQA/docformatter#293 Signed-off-by: Fabrice Normandin <fabrice.normandin@gmail.com> --------- Signed-off-by: Fabrice Normandin <normandf@mila.quebec> Signed-off-by: Fabrice Normandin <fabrice.normandin@gmail.com>
lebrice · Jan 31, 2025 · 91681dc · 91681dc
1 parent 27c5fa2
commit 91681dc
Show file tree

Hide file tree

Showing 10 changed files with 660 additions and 109 deletions.
diff --git a/.copier-answers.yml b/.copier-answers.yml
@@ -0,0 +1,8 @@
+# Changes here will be overwritten by Copier
+_commit: v0.0.3-2-ge44104f
+_src_path: gh:lebrice/tool_template
+project_description: Automagically generate yaml schemas for your Hydra config files.
+python_version: '3.10'
+tool_name: hydra_auto_schema
+your_email: fabrice.normandin@gmail.com
+your_name: Fabrice Normandin
diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
@@ -25,31 +25,34 @@ jobs:
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v3
         with:
-          python-version: "3.10"
-      - run: pip install 'pre-commit<4.0.0'
-      - run: pre-commit --version
-      - run: pre-commit install
-      - run: pre-commit run --all-files --show-diff-on-failure
+          version: "latest"
+          enable-cache: true
+          # https://github.com/astral-sh/setup-uv?tab=readme-ov-file#github-authentication-token
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache-suffix: "3.10"
+      - name: Install dependencies
+        run: uvx pre-commit run --all-files --show-diff-on-failure
 
-#   check_docs:
-#     needs: [linting]
-#     runs-on: ubuntu-latest
-#     steps:
-#       - uses: actions/checkout@v4
-#       - name: Install the latest version of uv
-#         uses: astral-sh/setup-uv@v3
-#         with:
-#           version: "latest"
-#           enable-cache: true
-#           # https://github.com/astral-sh/setup-uv?tab=readme-ov-file#github-authentication-token
-#           github-token: ${{ secrets.GITHUB_TOKEN }}
-#           cache-suffix: "3.10"
-#       - name: Install dependencies
-#         run: uv sync --frozen --extra docs
-#       - name: Build the documentation (strict mode)
-#         run: uv run mkdocs build --strict
+  check_docs:
+    needs: [linting]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true
+          # https://github.com/astral-sh/setup-uv?tab=readme-ov-file#github-authentication-token
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache-suffix: "3.10"
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Build the documentation (strict mode)
+        run: uv run mkdocs build --strict
 
   unit_tests:
     needs: [linting]

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,35 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+          enable-cache: true  # no need, uses the local uv cache.
+          # https://github.com/astral-sh/setup-uv?tab=readme-ov-file#github-authentication-token
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache-suffix: "3.10"
+
+      - name: Pin python-version
+        run: uv python pin 3.10
+
+      - name: Install dependencies
+        run: uv sync --extra docs --frozen
+
+      - name: Deploy docs
+        run: uv run mkdocs gh-deploy --force
+        # note: Checking if we really need the one below:
+        # uses: mhausenblas/mkdocs-deploy-gh-pages@1.9
+        # # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        # env:
+        #   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -14,7 +14,7 @@ jobs:
   publish:
     strategy:
       matrix:
-        python-version: [3.11]
+        python-version: [3.10]
         os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     environment: release
@@ -43,8 +43,3 @@ jobs:
 
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
-
-      # - name: Publish package (uv)
-      #   env:
-      #     UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
-      #   run: uv publish
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -35,7 +35,7 @@ repos:
     rev: "v0.6.9"
     hooks:
       - id: ruff
-        args: ["--line-length", "99", "--fix"]
+        args: ["--fix"]
         require_serial: true
 
   # python docstring formatting
@@ -44,7 +44,7 @@ repos:
     hooks:
       - id: docformatter
         language: python
-        args: [--in-place, --wrap-summaries=99, --wrap-descriptions=99]
+        args: [--in-place]
         require_serial: true
 
   # NOTE: Disabling this, since I'm having the glib-c2.29 weird bug.

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1 @@
+../README.md
diff --git a/docs/reference/hydra_auto_schema.md b/docs/reference/hydra_auto_schema.md
@@ -0,0 +1 @@
+::: hydra_auto_schema
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -0,0 +1,35 @@
+site_name: hydra_auto_schema Documentation
+theme:
+  name: material
+
+markdown_extensions:
+  - pymdownx.highlight: # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#configuration
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.magiclink
+
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          import:
+            - https://docs.pytest.org/en/stable/objects.inv
+            - https://docs.python.org/3/objects.inv
+          options:
+            docstring_style: google
+            members_order: source
+            annotations_path: brief
+            show_docstring_attributes: true
+            modernize_annotations: true
+            show_source: false
+            show_submodules: false
+            separate_signature: true
+            signature_crossrefs: true
+            show_signature_annotations: true
+            allow_inspection: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,8 +1,10 @@
 [project]
 name = "hydra-auto-schema"
-description = "Automagically generate yaml schemas for your Hydra config files"
+description = "Automagically generate yaml schemas for your Hydra config files."
 readme = "README.md"
-authors = [{ name = "Fabrice Normandin", email = "normandf@mila.quebec" }]
+authors = [
+    { name = "Fabrice Normandin", email = "fabrice.normandin@gmail.com" },
+]
 requires-python = ">=3.10"
 dependencies = [
     "docstring-parser>=0.16",
@@ -15,35 +17,46 @@ dependencies = [
     "watchdog>=5.0.3",
 ]
 dynamic = ["version"]
+
 [project.scripts]
 hydra-auto-schema = "hydra_auto_schema.__main__:main"
 
-[build-system]
-requires = ["hatchling", "uv-dynamic-versioning"]
-build-backend = "hatchling.build"
-
-
-[tool.hatch.version]
-source = "uv-dynamic-versioning"
+[dependency-groups]
+dev = [
+    "pytest>=8.3.3",
+    "pytest-cov>=5.0.0",
+    "uv-dynamic-versioning>=0.2.0",
+    "mkdocs-material>=9.5.44",
+    "mkdocstrings[python]>=0.27.0",
+    "black>=24.10.0",
+    "pytest-regressions>=2.6.0",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["hydra_auto_schema", "tests"]
 norecursedirs = [".venv"]
 addopts = ["--doctest-modules"]
 
 [tool.uv]
-dev-dependencies = [
-    "pytest>=8.3.3",
-    "pytest-regressions>=2.5.0",
-    "uv-dynamic-versioning>=0.2.0",
-    "pytest-cov>=5.0.0",
-    "pre-commit<4.0.0",
-]
 managed = true
 
 [tool.uv-dynamic-versioning]
 vcs = "git"
 style = "semver"
 
+[tool.ruff]
+line-length = 99
+
+[tool.docformatter]
+wrap-summaries = 99
+wrap-descriptions = 99
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
 [tool.hatch.build.targets.wheel]
 packages = ["hydra_auto_schema", "hydra_plugins"]
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"