feat: add a demo directive

.cz.toml

@@ -1,4 +1,4 @@
 [tool.commitizen]
 update_changelog_on_bump = false
-version = "0.1.11"
+version = "0.0.0"
 tag_format = "$version"

.devcontainer/devcontainer.json

@@ -1,8 +1,8 @@
 {
-	"name": "Python 3",
-	"image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
-	"features": {
-		"ghcr.io/devcontainers-contrib/features/nox:2": {}
-	},
-	"postCreateCommand": "python -m pip install commitizen"
+  "name": "Python 3",
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bullseye",
+  "features": {
+    "ghcr.io/devcontainers-contrib/features/nox:2": {}
+  },
+  "postCreateCommand": "python -m pip install commitizen"
 }

.github/workflows/unit.yaml

@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11"]
         include:
           - os: macos-latest # macos test
             python-version: "3.11"
@@ -30,4 +30,3 @@ jobs:
         run: python -m pip install nox
       - name: test the repository
         run: nox
-

.pre-commit-config.yaml

@@ -5,4 +5,4 @@ repos:
     rev: "v2.18.0"
     hooks:
       - id: commitizen
-        stages: [commit-msg]
+        stages: [commit-msg]

README.rst

@@ -1,20 +1,17 @@
+⚠️ This repository is still underconstruction DO NOT USE ⚠️
+
 Pypackage
 =========
 
-.. image:: https://img.shields.io/github/v/release/12rambau/pypackage?logo=github&logoColor=white
+.. image:: https://img.shields.io/github/v/release/sphinx-contrib/copier-sphinxcontrib?logo=github&logoColor=white
    :alt: GitHub release (with filter)
    :target: https://github.com/12rambau/pypackage/releases
 
 .. image:: https://img.shields.io/github/actions/workflow/status/12rambau/pypackage/unit.yaml?logo=github&logoColor=white
    :alt: GitHub Workflow Status (with event)
    :target: https://github.com/12rambau/pypackage/actions/workflows/unit.yaml
 
-.. image:: https://img.shields.io/readthedocs/12rambau-pypackage?logo=readthedocs&logoColor=white
-   :alt: Read the Docs
-   :target: https://12rambau-pypackage.readthedocs.io/en/latest/
-
-
-The skeleton of a python lib embeding what I like:
+The skeleton of a python lib embedding what I like:
 
 - pre-commit hooks (`prettier <https://prettier.io/>`__, `ruff <https://beta.ruff.rs/docs/>`__, `black <https://black.readthedocs.io>`__)
 - nox unit tests (doc, `pytest <https://docs.pytest.org>`__, `mypy <https://mypy.readthedocs.io>`__)

copier.yaml

@@ -1,18 +1,18 @@
 # questions
 project_name:
   typr: str
-  default: "Package skeleton"
-  help: "The name of the project"
+  default: "Skeleton"
+  help: "The name of the extension."
 
 github_repo_name:
   type: str
-  default: "{{ project_name.lower().replace(' ', '-') }}"
-  help: "The name of the GitHub repository"
+  default: "sphinxcontrib-{{ project_name.lower().replace(' ', '-') }}"
+  help: "The name of the GitHub repository AND pypi project"
 
 project_slug:
   type: str
-  default: "{{ github_repo_name.lower().replace('-', '_') }}"
-  help: "The slug that will be used to name the lib package"
+  default: "{{ project_name.lower().replace(' ', '_').replace('-', '_') }}"
+  help: "The slug that will be used to name the extension package"
 
 github_user:
   type: str
@@ -29,40 +29,35 @@ author_last_name:
   default: "Lastname"
   help: "The last name of the author"
 
-author_orcid:
-  type: str
-  default: "0000-0000-0000-0000"
-  help: "The ORCID ID of the author in case of scientific publication"
-
 author_email:
   type: str
   default: "{{ author_first_name.lower() }}.{{ author_last_name.lower() }}@domain.io"
   help: "The email of the author"
 
 short_description:
   type: str
-  default: "the skeleton of a python lib with everything I like"
-  help: "A short description of the project"
+  default: "the skeleton of a sphinx extension in the sphinxcontrib community"
+  help: "A short description of the extension"
 
 creation_year:
   type: str
   default: "{% now 'utc', '%Y' %}"
   help: "The creation date of your package, don't change unless it's a manual update"
 
 # copier internal parameters
-_subdirectory: "package"
+_subdirectory: "extension"
 _jinja_extensions: [jinja2_time.TimeExtension]
 _message_before_copy: |
-  ________   _______  ___  _____  _   __  ___  _____  ____
-  | ___ \ \ / / ___ \/ _ \/  __ \| | / / / _ \|  __ \|  __\
-  | |_/ /\ V /| |_/ / /_\ \ /  \/| |/ / / /_\ \ |  \/| |__
-  |  __/  \ / |  __/|  _  | |    |    \ |  _  | | __ |  __|
-  | |     | | | |   | | | | \__/\| |\  \| | | | |_\ \| |___
-  \_|     \_/ \_|   \_| |_/\____/\_| \_/\_| |_/\____/\____/
+  " ___________ _   _ _____ _   _ __   __      _______   _______ _____ _   _ _____ _____ _____ _   _ "
+  "/  ___| ___ \ | | |_   _| \ | |\ \ / /     |  ___\ \ / /_   _|  ___| \ | |_   _|_   _|  _  | \ | |"
+  "\ `--.| |_/ / |_| | | | |  \| | \ V /______| |__  \ V /  | | | |__ |  \| | | |   | | | | | |  \| |"
+  " `--. \  __/|  _  | | | | . ` | /   \______|  __| /   \  | | |  __|| . ` | | |   | | | | | | . ` |"
+  "/\__/ / |   | | | |_| |_| |\  |/ /^\ \     | |___/ /^\ \ | | | |___| |\  | | |  _| |_\ \_/ / |\  |"
+  "\____/\_|   \_| |_/\___/\_| \_/\/   \/     \____/\/   \/ \_/ \____/\_| \_/ \_/  \___/ \___/\_| \_/"
 _message_before_update: |
-  ________   _______  ___  _____  _   __  ___  _____  ____
-  | ___ \ \ / / ___ \/ _ \/  __ \| | / / / _ \|  __ \|  __\
-  | |_/ /\ V /| |_/ / /_\ \ /  \/| |/ / / /_\ \ |  \/| |__
-  |  __/  \ / |  __/|  _  | |    |    \ |  _  | | __ |  __|
-  | |     | | | |   | | | | \__/\| |\  \| | | | |_\ \| |___
-  \_|     \_/ \_|   \_| |_/\____/\_| \_/\_| |_/\____/\____/
+  " ___________ _   _ _____ _   _ __   __      _______   _______ _____ _   _ _____ _____ _____ _   _ "
+  "/  ___| ___ \ | | |_   _| \ | |\ \ / /     |  ___\ \ / /_   _|  ___| \ | |_   _|_   _|  _  | \ | |"
+  "\ `--.| |_/ / |_| | | | |  \| | \ V /______| |__  \ V /  | | | |__ |  \| | | |   | | | | | |  \| |"
+  " `--. \  __/|  _  | | | | . ` | /   \______|  __| /   \  | | |  __|| . ` | | |   | | | | | | . ` |"
+  "/\__/ / |   | | | |_| |_| |\  |/ /^\ \     | |___/ /^\ \ | | | |___| |\  | | |  _| |_\ \_/ / |\  |"
+  "\____/\_|   \_| |_/\___/\_| \_/\/   \/     \____/\/   \/ \_/ \____/\_| \_/ \_/  \___/ \___/\_| \_/"

package/.github/workflows/release.yaml.jinja → extension/.github/workflows/release.yaml.jinja

@@ -18,8 +18,6 @@ jobs:
           python-version: "3.10"
       - name: Install dependencies
         run: pip install twine build nox
-      - name: update citation date
-        run: nox -s release-date
       - name: Build and publish
         env:
           TWINE_USERNAME: __token__

package/.github/workflows/unit.yaml.jinja → extension/.github/workflows/unit.yaml.jinja

@@ -48,7 +48,7 @@ jobs:
       fail-fast: true
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11"]
         include:
           - os: macos-latest # macos test
             python-version: "3.11"

package/docs/conf.py.jinja → extension/docs/conf.py.jinja

@@ -58,7 +58,7 @@ html_css_files = ["custom.css"]
 
 # -- Options for autosummary/autodoc output ------------------------------------
 autodoc_typehints = "description"
-autoapi_dirs = ["../{{ project_slug }}"]
+autoapi_dirs = ["../sphinxcontrib/{{ project_slug }}"]
 autoapi_python_class_content = "init"
 autoapi_member_order = "groupwise"
 

package/noxfile.py.jinja → extension/noxfile.py.jinja

@@ -52,26 +52,5 @@ def docs(session):
 def mypy(session):
     """Run a mypy check of the lib."""
     session.install("mypy")
-    test_files = session.posargs or ["{{ project_slug }}"]
+    test_files = session.posargs or ["sphinxcontrib/{{ project_slug }}"]
     session.run("mypy", *test_files)
-
-
-@nox.session(reuse_venv=True)
-def stubgen(session):
-    """Generate stub files for the lib but requires human attention before merge."""
-    session.install("mypy")
-    package = session.posargs or ["{{ project_slug }}"]
-    session.run("stubgen", "-p", package[0], "-o", "stubs", "--include-private")
-
-
-@nox.session(name="release-date", reuse_venv=True)
-def release_date(session):
-    """Update the release date of the citation file."""
-    current_date = datetime.datetime.now().strftime("%Y-%m-%d")
-
-    with fileinput.FileInput("CITATION.cff", inplace=True) as file:
-        for line in file:
-            if line.startswith("date-released:"):
-                print(f'date-released: "{current_date}"')
-            else:
-                print(line, end="")

package/pyproject.toml.jinja → extension/pyproject.toml.jinja

@@ -21,6 +21,7 @@ classifiers = [
 ]
 requires-python = ">=3.8"
 dependencies = [
+  "sphinx",
   "deprecated>=1.2.14"
 ]
 
@@ -43,18 +44,19 @@ test = [
   "pytest",
   "pytest-sugar",
   "pytest-cov",
-  "pytest-deadfixtures"
+  "pytest-deadfixtures",
+  "pytest-regressions",
+  "beautifulsoup4",
 ]
 doc = [
-  "sphinx>=6.2.1",
   "pydata-sphinx-theme",
   "sphinx-copybutton",
   "sphinx-design",
   "sphinx-autoapi"
 ]
 
 [tool.hatch.build.targets.wheel]
-only-include = ["{{ project_slug }}"]
+packages = ["sphinxcontrib/{{ project_slug }}"]
 
 [tool.hatch.envs.default]
 dependencies = [
@@ -72,7 +74,6 @@ version_files = [
     "pyproject.toml:version",
     "{{ project_slug }}/__init__.py:__version__",
     "docs/conf.py:release",
-    "CITATION.cff:version"
 ]
 
 [tool.pytest.ini_options]
@@ -97,7 +98,7 @@ docstring-quotes = "double"
 convention = "google"
 
 [tool.coverage.run]
-source = ["{{ project_slug }}"]
+source = ["sphinxcontrib/{{ project_slug }}"]
 
 [tool.doc8]
 ignore = ["D001"] # we follow a 1 line = 1 paragraph style
@@ -111,3 +112,5 @@ warn_redundant_casts = true
 
 [tool.licensecheck]
 using = "PEP631"
+
+[tool.codespell]

extension/sphinxcontrib/{{project_slug}}/__init__.py.jinja

@@ -0,0 +1,32 @@
+"""The init file of the extension.
+
+This is where the extension is loaded and the sphinx builder is extended.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from sphinx.application import Sphinx
+
+from .demo_role import _NODE_VISITORS, DemoRole, demo_node
+from .demo_directive import DemoDirective
+
+__version__ = "0.0.0"
+__author__ = "{{ author_first_name }} {{ author_last_name }}"
+__email__ = "{{ author_email }}"
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add icon node to the sphinx builder."""
+    # add the node and role to the sphinx builder
+    app.add_node(demo_node, **_NODE_VISITORS)  # type: ignore
+    app.add_role("demo-role", DemoRole())
+
+    # add the directive to the sphinx builder
+    app.add_directive("demo-directive", DemoDirective)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

extension/sphinxcontrib/{{project_slug}}/demo_directive.py.jinja

@@ -0,0 +1,37 @@
+"""Demonstration of a custom directive for sphinx.
+
+This directive should be deleted when starting a new extention but it gives an overview
+of the different steps to follow to create a new directive. It is also used to demonstrate the
+documentation/test workflows.
+
+.. note::
+
+    We only coded a html output for this directive.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from yaml import safe_load
+
+logger = logging.getLogger(__name__)
+
+
+class DemoDirective(SphinxDirective):
+    """A demo directive simply setting the text in bold"""
+
+    arguments = 1
+    final_argument_whitespace = False
+    has_content = True
+
+    def run(self) -> List[nodes.Node]:
+        """Create the demo directive output."""
+        text = self.content[0].strip()
+        out = f'<div class="demo-directive"><b>{text}</b></div>'
+        return [nodes.raw("", out, format="html")]

extension/sphinxcontrib/{{project_slug}}/demo_role.py.jinja

@@ -0,0 +1,56 @@
+"""Demonstration of a custom role for sphinx.
+
+This role should be deleted when starting a new extension but it gives an overview
+of the different steps to follow to create a new role. It is also used to demonstrate the
+documentation/test workflows.
+
+.. note::
+
+    We only coded a html output for this role.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from docutils import nodes
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxRole, SphinxTranslator
+
+logger = logging.getLogger(__name__)
+
+class demo_node(nodes.General, nodes.Element):
+    """the demo node."""
+    pass
+
+class DemoRole(SphinxRole):
+    """The demo sphinxrole interpreter."""
+
+    def run(self) -> Tuple[List[nodes.Node], List[str]]:
+        """Setup the role in the builder context."""
+        return [demo_node(text=self.text, location=self.get_source_info())], []
+
+def visit_icon_node_unsuported(translator: SphinxTranslator, node: demo_node) -> None:
+    """Raise error when the requested output is not supported."""
+    msg = "Unsupported output format (node skipped)"
+    logger.warning(msg, location=node.get("location"))
+    raise nodes.SkipNode
+
+
+def visit_demo_node_html(translator: SphinxTranslator, node: demo_node) -> None:
+    """Visit the html output."""
+    translator.body.append(f'<b class="demo">{node["text"]}</b>')
+    return
+
+def depart_demo_node_html(translator: SphinxTranslator, node: demo_node) -> None:
+    """depart from the html output."""
+    return
+
+
+_NODE_VISITORS = {
+    "html": (visit_demo_node_html, depart_demo_node_html),
+    "latex": (visit_icon_node_unsuported, None),
+    "man": (visit_icon_node_unsuported, None),
+    "texinfo": (visit_icon_node_unsuported, None),
+    "text": (visit_icon_node_unsuported, None),
+    "epub": (visit_icon_node_unsuported, None),
+}