calliope-project / calliope

A multi-scale energy systems modelling framework
https://www.callio.pe
Apache License 2.0
287 stars 93 forks source link

Remove examples from documentation search #675

Open irm-codebase opened 3 weeks ago

irm-codebase commented 3 weeks ago

Description

It seems like MkDocs material is not very good at isolating notebook sections in searches.

This results in very long search sections that make searching the docs more difficult.

Example: searching source_unit will produce a very large search section because the search catches an example notebook (see the little 'ghost' image on the right to get an idea of how long this section is). image

Related links

Version

v0.7

Proposed change

I think this issue will pop up quite often because people will often search for a parameters to read what they do, and they are bound to be in some example.

Isolating every single case is probably hard to maintain, so I propose removing examples from the search altogether.

irm-codebase commented 3 weeks ago

Upon further inspection, the cause seems to be that mkdocs does not filter xarray dataset printouts well.

This is one of the commands that produces a lot of spam. In combination with def_dict in the model data attributes (see #639), it leads bad searches in the documents.

image

The solution is still the same, though: avoid searching notebooks.