Merge pull request #63 from python-project-templates/tkp/yardang

timkpaine · web-flow · commit 51ca39741e60 · 2025-07-01T23:42:14.000-04:00
Add yardang option, fixes #57
diff --git a/copier.yaml b/copier.yaml
@@ -65,3 +65,8 @@ python_version_primary:
     "3.12":
       value: "3.12"
   help: Primary version of Python to use in CI/CD
+
+add_docs:
+  type: bool
+  default: false
+  help: Add documentation using Yardang/Sphinx
diff --git a/cpp/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja b/cpp/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja
@@ -0,0 +1,23 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-ext/python/setup@main
+      - uses: actions-ext/node/setup@main
+      - run: uv pip install .
+      - run: uv pip install yardang
+      - run: yardang build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+          publish_dir: docs/html
diff --git a/cpp/.gitignore.jinja b/cpp/.gitignore.jinja
@@ -129,8 +129,9 @@ dmypy.json
 .pyre/
 
 # Documentation
-docs/_build/
 /site
+index.md
+docs/_build/
 docs/api
 docs/index.md
 docs/html
diff --git a/examples/cpp.yaml b/examples/cpp.yaml
@@ -1,5 +1,6 @@
 ---
-add_extension: cpp 
+add_docs: true
+add_extension: cpp
 email: 3105306+timkpaine@users.noreply.github.com
 github: python-project-templates
 project_description: A C++-Python project template
diff --git a/examples/js.yaml b/examples/js.yaml
@@ -1,5 +1,6 @@
 ---
-add_extension: js 
+add_docs: true
+add_extension: js
 email: 3105306+timkpaine@users.noreply.github.com
 github: python-project-templates
 project_description: A JavaScript-Python project template
diff --git a/examples/jupyter.yaml b/examples/jupyter.yaml
@@ -1,4 +1,5 @@
 ---
+add_docs: true
 add_extension: jupyter
 email: 3105306+timkpaine@users.noreply.github.com
 github: python-project-templates
diff --git a/examples/python.yaml b/examples/python.yaml
@@ -1,4 +1,5 @@
 ---
+add_docs: true
 add_extension: python
 email: 3105306+timkpaine@users.noreply.github.com
 github: python-project-templates
diff --git a/examples/rust.yaml b/examples/rust.yaml
@@ -1,4 +1,5 @@
 ---
+add_docs: true
 add_extension: rust
 email: 3105306+timkpaine@users.noreply.github.com
 github: python-project-templates
diff --git a/js/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja b/js/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja
@@ -0,0 +1,23 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-ext/python/setup@main
+      - uses: actions-ext/node/setup@main
+      - run: uv pip install .
+      - run: uv pip install yardang
+      - run: yardang build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+          publish_dir: docs/html
diff --git a/js/.gitignore.jinja b/js/.gitignore.jinja
@@ -125,8 +125,9 @@ dmypy.json
 .pyre/
 
 # Documentation
-docs/_build/
 /site
+index.md
+docs/_build/
 docs/api
 docs/index.md
 docs/html
diff --git a/jupyter/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja b/jupyter/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja
@@ -0,0 +1,23 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-ext/python/setup@main
+      - uses: actions-ext/node/setup@main
+      - run: uv pip install .
+      - run: uv pip install yardang
+      - run: yardang build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+          publish_dir: docs/html
diff --git a/jupyter/.gitignore.jinja b/jupyter/.gitignore.jinja
@@ -125,8 +125,9 @@ dmypy.json
 .pyre/
 
 # Documentation
-docs/_build/
 /site
+index.md
+docs/_build/
 docs/api
 docs/index.md
 docs/html
diff --git a/python/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja b/python/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja
@@ -0,0 +1,23 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-ext/python/setup@main
+      - uses: actions-ext/node/setup@main
+      - run: uv pip install .
+      - run: uv pip install yardang
+      - run: yardang build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+          publish_dir: docs/html
diff --git a/python/.gitignore b/python/.gitignore
@@ -125,11 +125,11 @@ dmypy.json
 .pyre/
 
 # Documentation
-docs/_build/
 /site
+index.md
+docs/_build/
 docs/api
 docs/index.md
-_template/labextension
 
 # Jupyter
 .ipynb_checkpoints
diff --git a/python/pyproject.toml.jinja b/python/pyproject.toml.jinja
@@ -115,3 +115,13 @@ section-order = ["future", "standard-library", "third-party", "first-party", "lo
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
+
+{%- if add_docs %}
+
+[tool.yardang]
+title = "{{ project_name }}"
+root = "README.md"
+pages = []
+use-autoapi = true
+
+{% endif -%}
diff --git a/rust/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja b/rust/.github/workflows/{% if add_docs %}docs.yaml{% endif %}.jinja
@@ -0,0 +1,23 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-ext/python/setup@main
+      - uses: actions-ext/node/setup@main
+      - run: uv pip install .
+      - run: uv pip install yardang
+      - run: yardang build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
+          publish_dir: docs/html
diff --git a/rust/.gitignore b/rust/.gitignore
@@ -125,8 +125,9 @@ dmypy.json
 .pyre/
 
 # Documentation
-docs/_build/
 /site
+index.md
+docs/_build/
 docs/api
 docs/index.md
 docs/html

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`---`
	`2`	`+add_docs: true`
`2`	`3`	`add_extension: jupyter`
`3`	`4`	`email: 3105306+timkpaine@users.noreply.github.com`
`4`	`5`	`github: python-project-templates`