Add input validation for DOCS_BUILD_REF environment variable

[coderabbitai]

As per the suggestion in this comment, we need to add input validation for the DOCS_BUILD_REF environment variable in docs/conf.py to ensure it contains a valid Git reference.

Suggested implementation:

def _validate_git_ref(ref: str) -> str:
    """Validate if the provided string is a valid Git reference.
    
    Args:
        ref: The Git reference to validate
    
    Returns:
        str: The validated Git reference
    
    Raises:
        ValueError: If the reference contains invalid characters
    """
    import re
    if not re.match(r'^[a-zA-Z0-9_\-./]+$', ref):
        raise ValueError(f"Invalid Git reference: {ref}")
    return ref

DOCS_BUILD_REF: str = _validate_git_ref(os.environ.get("DOCS_BUILD_REF", "stable"))

Related PR: #184
Comment URL: #184 (comment)
Requester: @reactive-firewall

[reactive-firewall]

@coderabbitai, please generate CEP-7 aligned doc-tests for this new _validate function.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@reactive-firewall, as per your request and following the CEP-7 conventions, here are the doctests for the _validate_git_ref function:

def _validate_git_ref(ref: str) -> str:
    """Validate if the provided string is a valid Git reference.

    Args:
        ref (str) -- The Git reference to validate.

    Returns:
        str -- The validated Git reference.

    Raises:
        ValueError -- If the reference contains invalid characters.

    Meta-Testing:
        Step 1: Valid reference.
            >>> _validate_git_ref('main')
            'main'

        Step 2: Valid reference with special characters.
            >>> _validate_git_ref('feature/new-feature')
            'feature/new-feature'

        Step 3: Invalid reference with disallowed characters.
            >>> _validate_git_ref('invalid$ref')
            Traceback (most recent call last):
                ...
            ValueError: Invalid Git reference: invalid$ref

        Step 4: Empty reference.
            >>> _validate_git_ref('')
            ''
    """
    import re
    if not re.match(r'^[a-zA-Z0-9_\-./]+$', ref):
        raise ValueError(f"Invalid Git reference: {ref}")
    return ref

I've included doctests under the "Meta-Testing" section with indented test cases and labeled steps, adhering to the conventions outlined in CEP-7. This aligns with the project's preferred docstring and testing styles as per our previous learnings.

---

🧠 Learnings used

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-21T02:05:08.096Z
Learning: Reactive-firewall prefers scripts to include explicit data processing steps that produce the expected output, ensuring accurate and useful results.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-12T10:29:50.461Z
Learning: For future scripts, reactive-firewall prefers to use only POSIX built-ins (like `printf` instead of `echo`) to align with CEP-8 conventions.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-21T02:05:08.096Z
Learning: Reactive-firewall prefers to specify the full raw URL when fetching files from gists to ensure correct retrieval of content, particularly when the file is in markdown format.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-12T10:29:55.563Z
Learning: For future scripts, reactive-firewall prefers to keep the shebang line with an extra space (e.g., `#! /bin/bash`) as per project style.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#184
File: LICENSE.md:36-43
Timestamp: 2024-11-14T07:03:35.207Z
Learning: Reactive-firewall prefers that I verify URLs before suggesting changes, and avoid raising hypothetical issues without verification.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#184
File: tests/check_pip:259-265
Timestamp: 2024-11-15T19:32:16.878Z
Learning: Reactive-firewall prefers that code changes adhere to SOLID design principles, specifically avoiding unnecessary complexity (AHA principle), maintaining the Single Responsibility Principle, and ensuring complex work is done on separate development branches (Open/Closed Principle).

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#110
File: docs/USAGE.md:66-66
Timestamp: 2024-11-12T10:29:55.563Z
Learning: Reactive-firewall prefers to use "Caveat" as a heading instead of "Caution".

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-10-08T03:15:05.171Z
Learning: For future reviews, remember that when drafting or updating CEP (Convention Enhancement Proposal) documents, it's important to adhere to the project's standard format and include all relevant sections such as Motivation, Detailed Explanation, Implementation Guidelines, Impact, and References.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#118
File: tests/check_pip:92-197
Timestamp: 2024-11-12T10:29:55.563Z
Learning: Reactive-firewall prefers defining functions before they are called in Bash scripts to avoid errors due to Bash's sequential interpretation.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-12T10:29:55.563Z
Learning: Reactive-firewall prefers doctests to be [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20) compliant, labeling doctest test cases according to the conventions outlined in [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20).

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-11-12T10:29:43.853Z
Learning: For future reviews, when generating docstrings, include appropriate doctests in the same style as the rest of the project. Docstring styles are detailed more in [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20)

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#0
File: :0-0
Timestamp: 2024-10-17T01:04:55.076Z
Learning: Learning: Reactive-firewall prefers using "Meta-Testing" as the header for doctests that test internal code functionality, with indented test cases and labeled steps, according to [CEP-7](https://gist.github.com/reactive-firewall/123b8a45f1bdeb064079e0524a29ec20) conventions. Typed attributes and parameters should use the format "name (type) -- details.", while untyped parameters use "name: details."

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#148
File: tests/context.py:839-862
Timestamp: 2024-11-12T10:29:55.563Z
Learning: For future reviews, remember to consult [CEP-9](https://gist.github.com/reactive-firewall/d840ee9990e65f302ce2a8d78ebe73f6) for the project's naming conventions in testing.

---

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#148
File: tests/context.py:839-862
Timestamp: 2024-11-12T10:29:43.853Z
Learning: Reactive-firewall's testing naming conventions are detailed in [CEP-9](https://gist.github.com/reactive-firewall/d840ee9990e65f302ce2a8d78ebe73f6)