Updated documentation

Author: dhondta

.github/copilot-instructions.md

@@ -10,19 +10,12 @@ Copilot MUST:
 - Avoid stylistic or formatting changes
 
 ## Context
-This project extends Python's codecs with many encoding/decoding schemes and CLI tools.
+This project extends Python's codecs with many encoding/decoding schemes and a CLI tool.
 It already includes a wide variety of bases, ciphers, compression, and niche encodings.
 
 ## Enhancement Guidelines
+When adding a new encoding, follow the guideline in the documentation at `docs/pages/howto.md`.
 
-When adding a new encoding:
-1. Check if it already exists in the project
-2. Follow the existing codec structure and naming conventions
-3. Provide:
-   - `encode()` implementation
-   - `decode()` implementation
-   - Registration into the codec registry
-4. Ensure CLI compatibility (if applicable)
 
 ## Implementation Constraints
 
@@ -33,28 +26,56 @@ When adding a new encoding:
 
 ## Testing
 
-Every new codec MUST include:
-- Unit tests (encode/decode roundtrip)
-- Edge cases (empty input, binary data if applicable)
+Every new codec:
+- SHOULD include a list of `__examples__` that tells the automated tests what encoding/decoding transformations need to be verified ; it this cannot be made, unit tests (encode/decode roundtrip) SHALL be provided in `tests/test_manual.py`
+- Edge cases (empty input, binary data if applicable), either in the `__examples__` list or in the explicit tests in `tests/test_manual.py`
 
 ## Documentation
 
-Each codec must include:
-- Short description
-- Reference (standard, RFC, or algorithm source)
-- Example usage
+Each codec SHALL comply with the following structure:
+
+    ```python
+    # -*- coding: UTF-8 -*-
+    """{{codec_long_name}} Codec - {{codec_short_name}} content encoding.
+
+    {{codec_description}}
+
+    This codec:
+    - en/decodes strings from str to str
+    - en/decodes strings from bytes to bytes
+    - decodes file content to str (read)
+    - encodes file content from str to bytes (write)
+
+    Reference: {{codec_source_hyperlink}}
+    """
+    from ..__common__ import *
+
+
+    __examples__ = {<<dictionary of examples with, as keys, a special format detailed hereafter and, as values, a dictionary mapping source to destination values (see sectino _Self-generated tests_)>>}
+    <<optional list of valid codec names to be used with the guessing mode (see _Codec names for the guessing mode_), in format "__guess__ = [...]">>]
+
+
+    <<constants here, including ENCMAP if the codec is a simple mapping (see section _Case 2: Encoding map_)>>
+    <<functions here, if the codec requires some additional logic, i.e. when it is not a mapping (see section _Case 1: Generic encoding definition_)>>
+
+
+    <<put the right add function (see section _Which `add` function ?_) here with its relevant parameters (see section _Generic arguments_)>>
+    ```
+
+In this template, `{{ ... }}` enclosures indicate codec's properties and `<< ... >>``enclosures indicate placeholder actions referring to steps from the documentation about how to make a codec at `docs/pages/howto.md`.
 
 ## Output Format (IMPORTANT)
 
 When asked to add a codec, Copilot should:
 1. Briefly justify the encoding (1–2 lines)
-2. Provide full implementation
-3. Provide tests
-4. Provide documentation snippet
+2. Provide full implementation (according to section _Adding a new codec to `codext`_ of the documentation at `docs/pages/howto.md`)
+3. Provide tests (according to section _Self-generated tests_)
+4. Add it to the `README.md` of the repository
+5. Propose the update of the documentation (under the relevant page for the category of codec)
 
 ## Explicit Non-Goals
 
 - No refactoring
 - No performance optimization passes
 - No linting-only changes
-- No CI/CD changes
+- No CI/CD changes

.github/pull_request_template.md

@@ -1,11 +1,8 @@
-## Type
-- [ ] New encoding (required)
-
 ## Checklist
 - [ ] No unrelated changes
 - [ ] Codec is new (not already implemented)
 - [ ] Tests included (if cannot be automated with `tests/test_generated`)
 - [ ] Documentation (included in the right page in `docs/pages/enc`)
 
 ## Description
-Explain the encoding and its source.
+Explain the encoding and its source.

.github/workflows/python-package.yml

@@ -10,8 +10,7 @@ on:
     branches: [ "main" ]
 
 permissions:
-  actions: write
-  id-token: write # for OIDC
+  id-token: write
   contents: read
 
 jobs:
@@ -53,6 +52,8 @@ jobs:
         pytest --cov=$package
   coverage:
     needs: [prepare, build]
+    permissions:
+      contents: write
     runs-on: ubuntu-latest
     env:
       cov_badge_path: docs/coverage.svg

docs/ADDING_CODECS.md

@@ -1,7 +1,7 @@
 site_author: dhondta
 site_name: "Codext - Extension of native codecs for Python"
 repo_url: https://github.com/dhondta/python-codext
-copyright: Copyright © 2021-2023 Alexandre D'Hondt
+copyright: Copyright © 2021-2026 Alexandre D'Hondt
 docs_dir: pages
 nav:
   - Introduction: index.md
@@ -37,6 +37,8 @@ extra:
       name: Alex on Twitter
 extra_css:
   - css/extra.css
+plugins:
+  - search
 theme:
   name: material
   palette:
@@ -50,7 +52,6 @@ theme:
         name: Switch to light mode
   logo: img/logo.png
   favicon: img/icon.png
-use_directory_urls: false
 markdown_extensions:
   - toc:
       permalink: true