Update documentation CI to target Github Pages

Use embedded script instead of 'Lowdown' to handle changelog, as
it doesn't seem to be maintained.

.github/workflows/docs-deploy.yml

@@ -0,0 +1,55 @@
+name: docs-deploy
+
+on:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Create Build Environment
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r ${GITHUB_WORKSPACE}/doc/requirements.txt
+          mkdir -p ${{runner.workspace}}/build
+
+      - name: Build documentation
+        run: |
+          sphinx-build -T -E -b html \
+            "${GITHUB_WORKSPACE}/doc" \
+            "${{runner.workspace}}/build"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ${{runner.workspace}}/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -2,8 +2,7 @@
 
 [![PyPi version](https://img.shields.io/pypi/v/pytest-cmake.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.python.org/pypi/pytest-cmake)
 [![CMake](https://img.shields.io/badge/CMake-3.20...3.29-blue.svg?logo=CMake&logoColor=blue)](https://cmake.org)
-[![Documentation](https://readthedocs.org/projects/pytest-cmake/badge/?version=stable)](https://pytest-cmake.readthedocs.io/en/stable/)
-[![Test](https://github.com/buddly27/pytest-cmake/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/buddly27/pytest-cmake/actions/workflows/test.yml)
+[![Test](https://github.com/python-cmake/pytest-cmake/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/python-cmake/pytest-cmake/actions/workflows/test.yml)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 This project provides convenient ways to use [Pytest](https://docs.pytest.org/)
@@ -48,4 +47,4 @@ Running the tests will display the status for each test collected as follows:
 ## Documentation
 
 Full documentation, including installation and setup guides, can be found at
-https://pytest-cmake.readthedocs.io/en/stable/
+https://python-cmake.github.io/pytest-cmake/

doc/_extensions/changelog.py

@@ -0,0 +1,92 @@
+from datetime import datetime
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.util.docutils import SphinxDirective
+
+
+class ReleaseDirective(SphinxDirective):
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    option_spec = {
+        "date": directives.unchanged_required
+    }
+
+    def run(self):
+        """Creates a section for release notes with version and date."""
+        version = self.arguments[0]
+
+        # Fetch today's date as default if no date is provided
+        today_date_str = datetime.now().strftime("%Y-%m-%d")
+        date_str = self.options.get("date", today_date_str)
+
+        try:
+            parsed_date = datetime.strptime(date_str, "%Y-%m-%d")
+            release_date = parsed_date.strftime("%e %B %Y")
+        except ValueError:
+            raise ValueError(f"Invalid date format: {date_str}")
+
+        # Create the version title node
+        version_node = nodes.strong(text=version)
+        section_title = nodes.title("", "", version_node)
+
+        # Create the section node with a specific ID
+        section_id = f"release-{version.replace(' ', '-')}"
+        section = nodes.section(
+            "", section_title,
+            ids=[section_id],
+            classes=["changelog-release"]
+        )
+
+        # Append formatted date
+        section.append(
+            nodes.emphasis(text=release_date, classes=["release-date"])
+        )
+
+        # Parse content into a list of changes
+        content_node = nodes.Element()
+        self.state.nested_parse(self.content, self.content_offset, content_node)
+
+        # Create a bullet list of changes
+        changes_list = nodes.bullet_list("", classes=["changelog-change-list"])
+        for child in content_node:
+            item = nodes.list_item("")
+            item.append(child)
+            changes_list.append(item)
+
+        section.append(changes_list)
+
+        return [section]
+
+
+class ChangeDirective(SphinxDirective):
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+
+    def run(self):
+        """Generates a categorized list item for a changelog entry."""
+        category = self.arguments[0]
+
+        # Create a paragraph for the category with specific styling
+        class_name = f"changelog-category-{category.lower().replace(' ', '-')}"
+        category_node = nodes.inline(
+            "", category,
+            classes=["changelog-category", class_name]
+        )
+        paragraph_node = nodes.paragraph("", "", category_node)
+
+        # Parse the detailed content under the category
+        content_node = nodes.container()
+        self.state.nested_parse(self.content, 0, content_node)
+        paragraph_node += content_node
+
+        return [paragraph_node]
+
+
+def setup(app):
+    """Register extension with Sphinx."""
+    app.add_directive("release", ReleaseDirective)
+    app.add_directive("change", ChangeDirective)
+

doc/_static/style.css

@@ -0,0 +1,63 @@
+.changelog-release {
+    position: relative;
+}
+
+.changelog-release > h1, h2, h3, h4, h5 {
+    margin-bottom: 5px;
+}
+
+.changelog-release em.release-date {
+    color: #999;
+    position: absolute;
+    line-height: 2.5em;
+    top: 0;
+    right: 0;
+}
+
+.changelog-release ul.changelog-change-list {
+    list-style: outside none none;
+}
+
+.changelog-release ul.changelog-change-list > li {
+    list-style: outside none none;
+    position: relative;
+    margin: 0;
+    padding: 8px 0 2px 120px;
+    border-top: 1px solid #D6D6D6;
+}
+
+.rst-content .section .changelog-change-list ul li {
+    list-style: initial;
+}
+
+.changelog-category {
+    border-right: 3px solid #CCC;
+    box-shadow: 0px 1px 1px rgba(0, 0, 0, 0.05), 0px -1px 0px rgba(0, 0, 0, 0.05) inset;
+    color: #333;
+    display: inline-block;
+    font-size: 0.7em;
+    font-style: normal;
+    font-weight: bold;
+    line-height: 14px;
+    padding: 4px 2px 4px 10px;
+    text-shadow: 1px 1px 0px #FFF;
+    text-transform: uppercase;
+    width: 102px;
+    position: absolute;
+    top: 10px;
+    left: 0px;
+    background-color: #f8f8f8;
+}
+
+.changelog-category-fixed {
+    border-color: #7C0;
+}
+
+.changelog-category-new {
+    border-color: #11B0E9;
+}
+
+.changelog-category-changed {
+    border-color: #EB3F3F;
+}
+

doc/conf.py

@@ -4,11 +4,15 @@
 
 import re
 import pathlib
+import sys
+
+root = pathlib.Path(__file__).parent.resolve()
+sys.path.insert(0, str(root / "_extensions"))
 
 # -- General ------------------------------------------------------------------
 
 # Extensions.
-extensions = ["lowdown", "sphinx.ext.intersphinx"]
+extensions = ["changelog", "sphinx.ext.intersphinx"]
 
 # The suffix of source filenames.
 source_suffix = ".rst"
@@ -22,7 +26,6 @@
 
 # Version
 pattern = r"version = \"([\d\\.]+)\""
-root = pathlib.Path(__file__).parent.resolve()
 config = (root.parent / "pyproject.toml").read_text(encoding="utf-8")
 
 version = re.search(pattern, config, re.DOTALL).group(1)
@@ -31,8 +34,9 @@
 # -- HTML output --------------------------------------------------------------
 
 html_theme = "sphinx_rtd_theme"
-
-# If True, copy source rst files to output for reference.
+html_favicon = "favicon.ico"
+html_static_path = ["_static"]
+html_css_files = ["style.css"]
 html_copy_source = True
 
 # -- Intersphinx --------------------------------------------------------------

doc/installing.rst

@@ -38,10 +38,10 @@ Installing from source
 
 You can also install the configuration manually from the source for more
 control. First, obtain a copy of the source by either downloading the
-`zipball <https://github.com/buddly27/pytest-cmake/archive/main.zip>`_ or
+`zipball <https://github.com/python-cmake/pytest-cmake/archive/main.zip>`_ or
 cloning the public repository::
 
-    git clone git@github.com:buddly27/pytest-cmake.git
+    git clone git@github.com:python-cmake/pytest-cmake.git
 
 Then you can build and install the package into your current Python
 environment::
@@ -101,7 +101,7 @@ code can be added before invoking the :term:`find_package` function:
 
 .. code-block:: cmake
 
-    set(pytest_url https://github.com/buddly27/pytest-cmake/archive/main.zip)
+    set(pytest_url https://github.com/python-cmake/pytest-cmake/archive/main.zip)
 
     # Fetch CMake files from the main branch of the Github repository
     file(DOWNLOAD ${pytest_url} ${CMAKE_BINARY_DIR}/pytest.zip)

doc/release/release_notes.rst

@@ -12,7 +12,7 @@ Release Notes
         Updated CMake script to ensure that environment variables are
 	preserving the Windows-style path syntax when running the tests.
 
-	.. seealso:: https://github.com/buddly27/pytest-cmake/issues/22
+	.. seealso:: https://github.com/python-cmake/pytest-cmake/issues/22
 
     .. change:: changed
 

doc/requirements.txt

@@ -1,3 +1,2 @@
-Lowdown==0.2.1
-Sphinx==5.1.1
-sphinx-rtd-theme==1.0.0
+Sphinx==7.3.7
+sphinx-rtd-theme==2.0.0

pyproject.toml

@@ -36,6 +36,12 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 
+[project.urls]
+Documentation = "https://python-cmake.github.io/pytest-cmake"
+Repository = "https://github.com/python-cmake/pytest-cmake"
+Issues = "https://github.com/python-cmake/pytest-cmake/issues"
+Changelog = "https://python-cmake.github.io/pytest-cmake/release/release_notes.html"
+
 [tool.hatch.build.hooks.custom]
 require-runtime-dependencies = true
 path = "build_config.py"