update docs, especially the contributing section

Signed-off-by: Grant Ramsay <[email protected]>

CONTRIBUTING.md

@@ -32,10 +32,10 @@ Mac OS X. For Windows, you can use the
 [here](https://github.com/pyenv-win/pyenv-win#installation ) for installation
 instructions.
 
-We also use [Poetry](https://python-poetry.org/) to manage our dependencies. You
-should have this installed as well. You can install Poetry by following the
-instructions on the [Poetry
-website](https://python-poetry.org/docs/#installation).
+From version `0.13.0` and forward, we use [uv](https://docs.astral.sh/uv/) to
+manage our dependencies (previously we used `Poetry`), so you should have this
+installed as well. You can install `uv` by following the instructions on the [uv
+website](https://docs.astral.sh/uv/getting-started/installation/).
 
 ## Getting Started
 
@@ -59,13 +59,13 @@ To get started, follow these steps:
 Run the following command to install the required dependencies:
 
 ```console
-$ poetry install
+$ uv sync
 ```
 
 You then need to activate the virtual environment:
 
 ```console
-$ poetry shell
+$ source .venv/bin/activate
 ```
 
 From here you can start working on the project. If you are using an IDE such as
@@ -74,16 +74,16 @@ the virtual environment that has just been created.
 
 ### Using Pip
 
-If you prefer to use `pip` instead of `poetry`, you can install the dependencies
+If you prefer to use `pip` instead of `uv`, you can install the dependencies
 using the auto-generated `requirements-dev.txt` file:
 
 ```console
 $ pip install -r requirements-dev.txt
 ```
 
-However, [Poetry](https://python-poetry.org/){:target="_blank"} is the
-recommended (and only supported) way of developing this project and is tightly
-integrated with the code and tools.
+However, [uv](https://docs.astral.sh/uv/){:target="_blank"} is the recommended
+(and only supported) way of developing this project and is tightly integrated
+with the code and tools.
 
 ## Linting
 
@@ -98,8 +98,7 @@ included `.vscode` folder has the settings for this.
 
 Please install this if you are intending to contribute to the project. It will
 check commits locally before they are pushed up to the Repo. The GitHub CI runs
-the linting checks (and in future probably MyPy as well), and will fail if there
-are any errors.
+the linting checks (and MyPy), and will fail if there are any errors.
 
 ```console
 $ pre-commit install

README.md

@@ -14,6 +14,14 @@ developing your Python applications quicker! Includes linting and Pytest
 libraries, a task runner, pre-commit hooks, and optionally create a git
 repository and upload to GitHub. you can also fully customize the template used.
 
+> [!NOTE]
+>
+> I have migrated the project (and my own workflow) to use
+> [uv](https://docs.astral.sh/uv/) as my dependency management and more, so all
+> new projects I create will use that instead of Poetry. For now, I will keep
+> the Poetry support as default in this project, but I will probably add a `uv`
+> option in the future to create new projects using that instead.
+
 Full documentation for this project with usage examples is available at
 <https://py-maker.seapagan.net/>
 

docs/hooks/__init__.py

@@ -0,0 +1 @@
+"""Define hooks for the documentation project."""

docs/hooks/google_style_notes.py

@@ -0,0 +1,52 @@
+"""Hook for MkDocs to support Google-style admonitions."""
+
+import re
+from typing import Any
+
+
+def on_page_markdown(markdown: str, **_: dict[str, Any]) -> str:
+    """Hook into the markdown rendering."""
+
+    def replace_admonition(match: re.Match[str]) -> str:
+        """Actually replace the admonition."""
+        type_map: dict[str, str] = {
+            "NOTE": "note",
+            "TIP": "tip",
+            "WARNING": "warning",
+            "IMPORTANT": "info",
+            "CAUTION": "danger",
+        }
+        original_type: str = match.group(1)
+        admonition_type: str = type_map[
+            original_type
+        ]  # Direct mapping without .lower()
+        content: str = match.group(2).strip()
+
+        # Convert original type to title case
+        title_case_type: str = original_type.title()
+
+        # Remove '>' from the beginning of each line and strip whitespace
+        content_lines: list[str] = [
+            line.lstrip(">").strip() for line in content.split("\n")
+        ]
+
+        # Remove any empty lines at the start of the content
+        while content_lines and not content_lines[0]:
+            content_lines.pop(0)
+
+        # Indent each non-empty line
+        indented_content: str = "\n".join(
+            f"    {line}" if line else "" for line in content_lines
+        )
+
+        return (
+            f'!!! {admonition_type} "{title_case_type}"\n\n{indented_content}\n'
+        )
+
+    # Use a single regex to match all admonition types and their content
+    pattern: str = (
+        r"^> \[!(NOTE|TIP|WARNING|IMPORTANT|CAUTION)\]\n>"
+        r"([\s\S]*?)(?=\n(?!>)|\Z)"
+    )
+
+    return re.sub(pattern, replace_admonition, markdown, flags=re.MULTILINE)

mkdocs.yml

@@ -23,9 +23,19 @@ extra:
       link: https://github.com/seapagan/py-maker
     - icon: fontawesome/brands/twitter
       link: https://twitter.com/gnramsay_dev
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
 
 copyright: © 2023-2024 Grant Ramsay (Seapagan)
 
+hooks:
+  - docs/hooks/google_style_notes.py
+
 plugins:
   - search
   - git-revision-date-localized: