Update the project

Author: braboj

.github/workflows/deploy_pages.yml

@@ -26,6 +26,8 @@ jobs:
         with:
           python-version: 3.12
       - run: pip install -r requirements.txt
+      - run: ./scripts/gen_markdown_chapters.py
+      - run: copy docs/README.md docs/index.md
       - run: mkdocs build --site-dir ./_site
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3.0.1

.scripts/gen_markdown_chapters.py

@@ -1,12 +1,12 @@
 #!/usr/bin/env python3
-"""Generate aggregated Markdown files for each .examples subfolder.
+"""Generate aggregated Markdown files for each examples subfolder.
 
 Usage:
     python .scripts/gen_markdown_chapters.py \
-        --.examples-dir .examples \
+        --examples-dir examples \
         --output-dir docs
 
-For every immediate subfolder in ``.examples`` a single ``.md`` file is created
+For every immediate subfolder in ``examples`` a single ``.md`` file is created
 in the output directory. The file name matches the subfolder name and contains
 all example files from that folder. Folder and file names are converted to
 title format: CamelCase words are split with spaces and acronyms remain in
@@ -55,7 +55,7 @@ def to_title(name: str) -> str:
     return " ".join(words)
 
 def generate_aggregate(folder: Path, output_dir: Path) -> None:
-    """Create a single Markdown file aggregating all .examples in *folder*."""
+    """Create a single Markdown file aggregating all examples in *folder*."""
     examples = []
     for py_file in sorted(folder.glob("*.py")):
         if py_file.name == "__init__.py":
@@ -84,16 +84,16 @@ def generate_aggregate(folder: Path, output_dir: Path) -> None:
 def main() -> None:
 
     parser = argparse.ArgumentParser(
-        description="Generate aggregated Markdown files from the .examples"
+        description="Generate aggregated Markdown files from the examples"
     )
     parser.add_argument(
-        "--.examples-dir",
-        default="../.examples",
+        "--examples-dir",
+        default="../examples",
         help="Directory containing example .py files",
     )
     parser.add_argument(
         "--output-dir",
-        default="../docs/.examples",
+        default="../docs",
         help="Directory where Markdown files will be written",
     )
     args = parser.parse_args()

.scripts/gen_markdown_pages.py

@@ -3,11 +3,11 @@
 
 Usage:
     python .scripts/gen_markdown_pages.py \
-        --.examples-dir .examples \
+        --examples-dir examples \
         --template templates/example_file.mustache \
         --output-dir docs
 
-The directory structure under ``.examples`` is mirrored under the output
+The directory structure under ``examples`` is mirrored under the output
 directory. Each ``.py`` file becomes a ``.md`` file with the same name and
 relative path. Files named ``__init__.py`` are ignored and skipped.
 """
@@ -50,11 +50,11 @@ def process_file(py_path: Path, template: str, base_dir: Path, output_dir: Path)
 
 def main() -> None:
     parser = argparse.ArgumentParser(
-        description="Generate Markdown files mirroring the .examples directory"
+        description="Generate Markdown files mirroring the examples directory"
     )
     parser.add_argument(
-        "--.examples-dir",
-        default="../.examples",
+        "--examples-dir",
+        default="../examples",
         help="Directory containing example .py files",
     )
     parser.add_argument(

.scripts/gen_single_markdown.py

@@ -3,9 +3,9 @@
 
 Usage::
     python .scripts/gen_single_markdown.py \
-        --.examples-dir .examples \
+        --examples-dir examples \
         --template templates/examples_page.mustache \
-        --output .examples.md
+        --output examples.md
 
 Each file's content is inserted verbatim as a code block in the output.  Files
 named ``__init__.py`` are ignored.
@@ -48,16 +48,16 @@ def render_markdown(template_path: Path, output_path: Path, examples: list) -> N
     with template_path.open("r", encoding="utf-8") as f:
         template = f.read()
     renderer = pystache.Renderer()
-    markdown = renderer.render(template, {".examples": examples})
+    markdown = renderer.render(template, {"examples": examples})
     with output_path.open("w", encoding="utf-8") as f:
         f.write(markdown)
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(description="Generate .examples markdown")
+    parser = argparse.ArgumentParser(description="Generate examples markdown")
     parser.add_argument(
-        "--.examples-dir",
-        default="../.examples",
+        "--examples-dir",
+        default="../examples",
         help="Directory containing example .py files",
     )
     parser.add_argument(
@@ -67,7 +67,7 @@ def main() -> None:
     )
     parser.add_argument(
         "--output",
-        default="../docs/.examples.md",
+        default="../docs/examples.md",
         help="Output markdown file",
     )
     args = parser.parse_args()