De-boost reference docs; add search gadgets (#671)

calliope-project · Sep 6, 2024 · 389e9f2 · 389e9f2
1 parent 3cd8caf
commit 389e9f2
Show file tree

Hide file tree

Showing 12 changed files with 69 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ### User-facing changes
 
+|changed| API/schema documentation is de-ranked in documentation search bar results (#670).
+
 |new| Math component cross-references in both directions ("uses" and "used in") in Markdown math documentation (#643).
 
 |fixed| Duplicated links in math documentation (#651).

diff --git a/docs/hooks/generate_readable_schema.py b/docs/hooks/generate_readable_schema.py
@@ -8,6 +8,7 @@
 """
 
 import tempfile
+import textwrap
 from pathlib import Path
 
 import jsonschema2md
@@ -55,7 +56,16 @@ def _schema_to_md(schema: dict, filename: str, config: dict) -> File:
     assert lines[2] == "## Properties\n\n"
     del lines[2]
 
-    output_full_filepath.write_text("\n".join(lines))
+    initial_lines = textwrap.dedent(
+        """
+        ---
+        search:
+          boost: 0.25
+        ---
+
+        """
+    )
+    output_full_filepath.write_text(initial_lines.lstrip() + "\n".join(lines))
 
     return File(
         path=output_file,

diff --git a/docs/reference/api/attrdict.md b/docs/reference/api/attrdict.md
@@ -1 +1,6 @@
-::: calliope.attrdict.AttrDict
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.attrdict.AttrDict
diff --git a/docs/reference/api/backend_model.md b/docs/reference/api/backend_model.md
@@ -1 +1,6 @@
-::: calliope.backend.backend_model.BackendModel
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.backend.backend_model.BackendModel
diff --git a/docs/reference/api/example_models.md b/docs/reference/api/example_models.md
@@ -1 +1,6 @@
-::: calliope.examples
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.examples
diff --git a/docs/reference/api/exceptions.md b/docs/reference/api/exceptions.md
@@ -1 +1,6 @@
-::: calliope.exceptions
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.exceptions
diff --git a/docs/reference/api/helper_functions.md b/docs/reference/api/helper_functions.md
@@ -1 +1,6 @@
-::: calliope.backend.helper_functions
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.backend.helper_functions
diff --git a/docs/reference/api/logging.md b/docs/reference/api/logging.md
@@ -1 +1,6 @@
-::: calliope.util.logging
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.util.logging
diff --git a/docs/reference/api/model.md b/docs/reference/api/model.md
@@ -1 +1,6 @@
-::: calliope.Model
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.Model
diff --git a/docs/reference/api/schema.md b/docs/reference/api/schema.md
@@ -1 +1,6 @@
-::: calliope.util.schema
+---
+search:
+    boost: 0.5
+---
+
+::: calliope.util.schema
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -1,3 +1,8 @@
+---
+search:
+    boost: 0.5
+---
+
 # CLI Reference
 
 This page provides documentation for the `calliope` command line tool.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -25,6 +25,9 @@ theme:
     - navigation.top
     - content.code.copy
     - content.code.annotate
+    - search.suggest
+    - search.highlight
+    - search.share
   logo: img/logo-bw.png
   favicon: img/favicon.ico
 extra_css: