doc: fix installation guide, add doc build info

README.md

@@ -33,6 +33,21 @@ To run the tests, do:
     pytest --ckan-ini=test.ini
 
 
+## Building the documentation
+
+We are using `mkdocs` to build the documentation. To build and deploy the documentation, do:
+
+    CHARTS_FIELDS=1 mkdocs build && mkdocs gh-deploy
+
+We need to set the `CHARTS_FIELDS` for our custom handler, that autogenerate documentation
+for chart types fields.
+
+If you're working on the documentation, you can run the following command to start a live-reloading server without
+gathering the chart types fields data. It will speed up the process significantly, as we won't need to wait for the
+CKAN initialization:
+
+    mkdocs serve -a 127.0.0.1:8001
+
 ## License
 
 [AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html)

docs/install.md

@@ -23,7 +23,7 @@ Compatibility with core CKAN versions:
     pip install ckanext-charts[pyarrow]
     ```
 
-2. Enable the main plugin and harvesters you want to use in your CKAN configuration file (e.g. `ckan.ini` or `production.ini`):
+2. Enable the view and builder plugins in your CKAN configuration file (e.g. `ckan.ini` or `production.ini`):
 
     ```ini
     ckan.plugins = ... charts_view charts_builder_view ...

mkdocstrings_handlers/ChartFieldsHandler/handler.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import os
-import importlib
 from typing import Mapping, MutableMapping, Any
 from unittest.mock import patch, MagicMock
 
@@ -19,7 +18,7 @@
 
 
 class ChartFieldsHandler(BaseHandler):
-    """Custom handler for documenting the chart engine fields according to the
+    """Custom handler for documenting different chart types fields according to the
     form fields schema."""
     def collect(
         self, identifier: str, config: MutableMapping[str, Any]

site/404.html

@@ -12,7 +12,7 @@
 
 
       <link rel="icon" href="/ckanext-charts/image/favicon.ico">
-      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.42">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.44">
 
 
 

site/assets/_mkdocstrings.css

@@ -26,20 +26,33 @@
   float: right;
 }
 
+/* Parameter headings must be inline, not blocks. */
+.doc-heading-parameter {
+  display: inline;
+}
+
+/* Prefer space on the right, not the left of parameter permalinks. */
+.doc-heading-parameter .headerlink {
+  margin-left: 0 !important;
+  margin-right: 0.2rem;
+}
+
 /* Backward-compatibility: docstring section titles in bold. */
 .doc-section-title {
   font-weight: bold;
 }
 
 /* Symbols in Navigation and ToC. */
-:root,
+:root, :host,
 [data-md-color-scheme="default"] {
+  --doc-symbol-parameter-fg-color: #df50af;
   --doc-symbol-attribute-fg-color: #953800;
   --doc-symbol-function-fg-color: #8250df;
   --doc-symbol-method-fg-color: #8250df;
   --doc-symbol-class-fg-color: #0550ae;
   --doc-symbol-module-fg-color: #5cad0f;
 
+  --doc-symbol-parameter-bg-color: #df50af1a;
   --doc-symbol-attribute-bg-color: #9538001a;
   --doc-symbol-function-bg-color: #8250df1a;
   --doc-symbol-method-bg-color: #8250df1a;
@@ -48,12 +61,14 @@
 }
 
 [data-md-color-scheme="slate"] {
+  --doc-symbol-parameter-fg-color: #ffa8cc;
   --doc-symbol-attribute-fg-color: #ffa657;
   --doc-symbol-function-fg-color: #d2a8ff;
   --doc-symbol-method-fg-color: #d2a8ff;
   --doc-symbol-class-fg-color: #79c0ff;
   --doc-symbol-module-fg-color: #baff79;
 
+  --doc-symbol-parameter-bg-color: #ffa8cc1a;
   --doc-symbol-attribute-bg-color: #ffa6571a;
   --doc-symbol-function-bg-color: #d2a8ff1a;
   --doc-symbol-method-bg-color: #d2a8ff1a;
@@ -68,6 +83,15 @@ code.doc-symbol {
   font-weight: bold;
 }
 
+code.doc-symbol-parameter {
+  color: var(--doc-symbol-parameter-fg-color);
+  background-color: var(--doc-symbol-parameter-bg-color);
+}
+
+code.doc-symbol-parameter::after {
+  content: "param";
+}
+
 code.doc-symbol-attribute {
   color: var(--doc-symbol-attribute-fg-color);
   background-color: var(--doc-symbol-attribute-bg-color);

site/caching/base/index.html

@@ -18,7 +18,7 @@
 
 
       <link rel="icon" href="../../image/favicon.ico">
-      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.42">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.44">
 
 
 
@@ -1071,6 +1071,11 @@ <h1 id="base-cache-strategy">Base Cache Strategy</h1>
 
 
 
+
+
+
+
+
   <div class="doc doc-children">
 
 
@@ -1108,7 +1113,9 @@ <h2 id="charts.cache.CacheStrategy.get_data" class="doc doc-heading">
       </thead>
       <tbody>
           <tr class="doc-section-item">
-            <td><code>key</code></td>
+            <td>
+                <code>key</code>
+            </td>
             <td class="doc-param-details">
               <div class="doc-md-description">
                 <p>The cache  key to retrieve the data.</p>
@@ -1179,7 +1186,9 @@ <h2 id="charts.cache.CacheStrategy.invalidate" class="doc doc-heading">
       </thead>
       <tbody>
           <tr class="doc-section-item">
-            <td><code>key</code></td>
+            <td>
+                <code>key</code>
+            </td>
             <td class="doc-param-details">
               <div class="doc-md-description">
                 <p>The cache key to invalidate.</p>
@@ -1226,7 +1235,9 @@ <h2 id="charts.cache.CacheStrategy.set_data" class="doc doc-heading">
       </thead>
       <tbody>
           <tr class="doc-section-item">
-            <td><code>key</code></td>
+            <td>
+                <code>key</code>
+            </td>
             <td class="doc-param-details">
               <div class="doc-md-description">
                 <p>The cache key to store the data.</p>
@@ -1240,7 +1251,9 @@ <h2 id="charts.cache.CacheStrategy.set_data" class="doc doc-heading">
             </td>
           </tr>
           <tr class="doc-section-item">
-            <td><code>data</code></td>
+            <td>
+                <code>data</code>
+            </td>
             <td class="doc-param-details">
               <div class="doc-md-description">
                 <p>The data to be stored.</p>