Docs update

.github/workflows/doc.yml

@@ -22,10 +22,10 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-      - name: Set up Python 3.11
+      - name: Set up Python 3.12
         uses: actions/setup-python@v6
         with:
-          python-version: 3.11
+          python-version: 3.12
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -43,7 +43,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: github-pages
-      url: ${{steps.deployment.outputs.page_url}}
+      url: ${{ format('{0}docs/', steps.deployment.outputs.page_url) }}
     needs: build
     steps:
       - name: Deploy to GitHub Pages

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for considering a contribution to fillname. ❤️
+Thanks for considering a contribution to fillname.
 
 ## How to get help or discuss possible contributions
 
@@ -16,7 +16,7 @@ To avoid duplicating issues, please search our [issue tracker][issues] and our
   changes.
 - Submit a pull request to the master branch with your changes.
 - Respond to feedback on your pull request.
-- If everything is fine your pull request is merged. 🥳
+- If everything is fine your pull request is merged!
 
 ## License
 

DEPLOYMENT.md

@@ -18,8 +18,9 @@ new tag. To enable this:
 - Navigate to **Settings** > **Pages**.
 - Under **Build and deployment**, set **Source** to **GitHub Actions**.
 
-This setup ensures your documentation is updated and available online whenever
-you create a new release tag via Github workflows.
+This setup ensures your documentation is updated whenever you create a new
+release tag via GitHub workflows. The final documentation will be made
+available at `https://potassco.org/fillname/docs`.
 
 [environment]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment/
 [guide]: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

DEVELOPMENT.md

@@ -1,5 +1,11 @@
 # Development
 
+To install the project in development mode, use the following command:
+
+```bash
+pip install -e .[dev]
+```
+
 To improve code quality, we use [nox] to run linters, type checkers, unit
 tests, and more. We recommend installing nox using [pipx] to have it available
 globally.

docs/SUMMARY.md

@@ -0,0 +1,16 @@
+* Getting Started
+    * [Quick Start Guide](use/quick-start.md)
+    * [Installation](use/installation.md)
+    * [Help](use/help.md)
+* Reference
+    * [Reference](reference/index.md)
+    * [Encodings](reference/encodings/index.md)
+    * [API](reference/api/index.md)
+    * [CLI](reference/cli/index.md)
+* Examples
+    * [Examples](examples/index.md)
+* Community
+    * [Contributing](community/CONTRIBUTING.md)
+    * [Changes](community/CHANGES.md)
+    * [Development](community/DEVELOPMENT.md)
+    * [Deployment](community/DEPLOYMENT.md)

docs/_custom/css/extra.css

@@ -38,11 +38,15 @@
     --md-code-hl-variable-color: hsl(24, 80%, 68%);
 }
 
-
 .md-grid {
     max-width: 1350px;
 }
 
+
+/* ============================================================
+   Header
+   ============================================================ */
+
 .md-header__title {
     font-size: 1.2rem;
     height: 2.5rem;
@@ -51,7 +55,6 @@
 }
 
 .md-header__button.md-logo {
-    /* margin-left: 30; */
     padding-bottom: 0.8rem;
 }
 
@@ -60,3 +63,83 @@
     height: 1.5rem;
     width: 1.5rem;
 }
+
+
+/* ============================================================
+   Admonitions
+   ============================================================ */
+
+.md-typeset .admonition,
+.md-typeset details {
+    border-width: 0;
+    border-left-width: 3px;
+}
+
+/* info / note / abstract / tip — primary color */
+.md-typeset .info>.admonition-title,
+.md-typeset .info>summary,
+.md-typeset .note>.admonition-title,
+.md-typeset .note>summary,
+.md-typeset .abstract>.admonition-title,
+.md-typeset .abstract>summary,
+.md-typeset .tip>.admonition-title,
+.md-typeset .tip>summary {
+    border-color: var(--md-primary-fg-color);
+    background-color: color-mix(in srgb, var(--md-primary-fg-color) 10%, transparent);
+}
+
+.md-typeset .admonition.info,
+.md-typeset details.info,
+.md-typeset .admonition.note,
+.md-typeset details.note,
+.md-typeset .admonition.abstract,
+.md-typeset details.abstract,
+.md-typeset .admonition.tip,
+.md-typeset details.tip {
+    border-color: var(--md-primary-fg-color);
+}
+
+.md-typeset .info>.admonition-title::before,
+.md-typeset .info>summary::before,
+.md-typeset .note>.admonition-title::before,
+.md-typeset .note>summary::before,
+.md-typeset .abstract>.admonition-title::before,
+.md-typeset .abstract>summary::before,
+.md-typeset .tip>.admonition-title::before,
+.md-typeset .tip>summary::before {
+    background-color: var(--md-primary-fg-color);
+}
+
+/* question — yellow */
+.md-typeset .question>.admonition-title,
+.md-typeset .question>summary {
+    border-color: #A8AD00;
+    background-color: color-mix(in srgb, #A8AD00 10%, transparent);
+}
+
+.md-typeset .admonition.question,
+.md-typeset details.question {
+    border-color: #A8AD00;
+}
+
+.md-typeset .question>.admonition-title::before,
+.md-typeset .question>summary::before {
+    background-color: #A8AD00;
+}
+
+/* success — green */
+.md-typeset .success>.admonition-title,
+.md-typeset .success>summary {
+    border-color: #2E7D32;
+    background-color: color-mix(in srgb, #2E7D32 10%, transparent);
+}
+
+.md-typeset .admonition.success,
+.md-typeset details.success {
+    border-color: #2E7D32;
+}
+
+.md-typeset .success>.admonition-title::before,
+.md-typeset .success>summary::before {
+    background-color: #2E7D32;
+}