Merge pull request #174 from brightway-lca/docusearch_algolia

Add DocSearch/Algolia

Author: michaelweinold

environment.yaml

@@ -21,3 +21,7 @@ dependencies:
   - sphinx-copybutton=0.5.2 # for copy button in code blocks # https://anaconda.org/conda-forge/sphinx-copybutton/files
   # build process
   - sphinx-autobuild=2024.9.17 # live-html support # https://anaconda.org/conda-forge/sphinx-autobuild/files
+  # other packages
+  - pip
+  - pip:
+    - sphinx-docsearch

source/_templates/autoapi/index.rst

@@ -0,0 +1,13 @@
+API
+===
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages|selectattr("is_top_level_object") %}
+   {{ page.include_path }}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_

source/conf.py

@@ -44,6 +44,8 @@
     "sphinx_copybutton",
     # hover-over tooltips for cross-references
     # 'hoverxref.extension', # currently no support for markdown as per https://github.com/readthedocs/sphinx-hoverxref/issues/250
+    # powerful search engine
+    "sphinx_docsearch",
 ]
 
 root_doc = 'index'
@@ -81,13 +83,15 @@
 
 html_sidebars = {
     "**": [
-        "search-field.html",
         "sidebar-nav-bs.html",
     ],
+    "content/contact/contact": [],
+    "content/other/support": [],
+    "content/other/credits": [],
 }
 
 html_theme_options = {
-    "announcement": "<p><a href='https://2024.brightcon.link/'>REGISTER NOW</a>: Brightcon 2024 Hybrid Conference and Hackathon 🇩🇪 September 23 - 27 in Hamburg</p>",
+    # "announcement": "<p><a href='https://2024.brightcon.link/'>REGISTER NOW</a>: Brightcon 2024 Hybrid Conference and Hackathon 🇩🇪 September 23 - 27 in Hamburg</p>",
     # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html
     "switcher": {
         "json_url": "https://raw.githubusercontent.com/brightway-lca/brightway-documentation/main/source/_static/switcher.json",
@@ -100,7 +104,7 @@
     "footer_start": ["copyright"],
     "footer_end": ["footer"],
     "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink", "support"],
-    "header_links_before_dropdown": 8,
+    "header_links_before_dropdown": 7,
     # page elements content
     "icon_links": [
         {
@@ -147,6 +151,15 @@
 ### Extension Configuration ########################################################################
 ####################################################################################################
 
+# sphinx DocSearch configuration #########################################
+
+# "exposed anyway", so we can just set the values here
+# https://sphinx-docsearch.readthedocs.io/credentials.html
+
+docsearch_app_id = "AB3D1FH6W0"
+docsearch_api_key = "5f985eef1633581416cd50fb544ab61c"
+docsearch_index_name = "brightway"
+
 # copybutton Configuration ###############################################
 
 copybutton_prompt_text = ">>>"
@@ -214,6 +227,8 @@
 autoapi_root = 'content/api'
 autoapi_keep_files = True
 
+autoapi_template_dir = '_templates/autoapi' # https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#how-to-customise-the-index-page
+
 # myst_parser Configuration ############################################
 # https://myst-parser.readthedocs.io/en/latest/configuration.html
 

source/content/contact/contact.md

@@ -9,12 +9,13 @@ The Brightway community is active and growing. There are many ways to get in tou
 | Mailing Lists | [`brightway.groups.io`](https://brightway.groups.io/) | Time-tested old-school-cool e-mail chains |
 | Chat Rooms | [`brightway:matrix.org`](https://matrix.to/#/#brightway:matrix.org) | Real-time chat with markdown support and end-to-end encryption |
 | Stack Overflow | [`tagged/brightway`](https://stackoverflow.com/questions/tagged/brightway) | Questions and answers on the most popular software development website |
-| Development Blog | [`chris.mutel.org`](https://chris.mutel.org/) | In-depth description of speficic improvements and development of Brightway | 
+| Chris' Blog | [`chris.mutel.org`](https://chris.mutel.org/) | In-depth description of developments related to Brightway | 
 
 ## Meet and Learn in Person
 
 | Event | Location | Description |
 | ----- | -------- | ----------- | 
-| [Brightcon Conference](http://brightcon.link) | Luxembourg (2023) | Annual user and developer conference with hackathon and workshops |
+| [Brightcon Conference](http://brightcon.link) | Europe | Annual user and developer conference with hackathon and workshops |
+| [DdS Brightway Schools](https://www.d-d-s.ch) | Europe, Americas, Asia | Regular training courses on Brightway and LCA |
 
 ![image](_images/brightcon_banner.jpg)

source/index.md

@@ -39,11 +39,10 @@ Learn more {fas}`arrow-right`
 
 ## What's New?
 
-__September 2024__: New [Cheat Sheet](./content/cheatsheet/index.md) with all common Brightway commands. Thank you, @[Chris Mutel](https://github.com/cmutel) \
-__May 2024__: New section `Getting Started` added to the documentation (since replaced by the `Cheat Sheet`). This section will help you kickstart your first Brightway project. Thank you, @[KarinTreyer](https://github.com/KarinTreyer) and @[michaelweinold](https://github.com/michaelweinold)! \
-__April 2024__: New section [Terminology](./content/theory/terminology.md) added to the documentation. This section explains the most important terms used in the Brightway documentation. Thank you, @[marc-vdm](https://github.com/marc-vdm)! \
-__April 2024__: New sub-section [Teaching Materials](./content/examples/index.md) added to the documentation. This section collects materials used to teach Brightway. Thank you, @[KarinTreyer](https://github.com/KarinTreyer)!
-
+__October 2024__: New AI-powered [Algolia/DocSearch](https://docsearch.algolia.com) search engine. Thank you, @[michaelweinold](https://github.com/michaelweinold)! \
+__September 2024__: Updated [Cheat Sheet](./content/cheatsheet/index.md) with all common Brightway commands. Thank you, @[cmutel](https://github.com/cmutel)! \
+__May 2024__: Initial [Cheat Sheet](./content/cheatsheet/index.md) with some common Brightway commands. Thank you, @[KarinTreyer](https://github.com/KarinTreyer) and @[michaelweinold](https://github.com/michaelweinold)! \
+__April 2024__: New [Glossay](./content/overview/glossary.md) page explaining the most important Brightway terms. Thank you, @[marc-vdm](https://github.com/marc-vdm)!
 
 ```{toctree}
 ---