mkdocs-gallery sort tutorials & configs

[BalzaniEdoardo]

mkdocs-gallery custom configurations

If one want to configure the mkdocs-gallery behavior, the way to do it is to create a file in docs/ named gallery_conf.py.

A template for the file, which just set the default configs, can be found in the github page of mkdocs-gallery. This script adds a dependency on plotly.

Default configurations can be found in mkdocs_gallery/gen_gallery.py, and are stored in a dictionary named DEFAULT_GALLERY_CONF. The documentation is scarce, but some things are intuitive and others can be reverse engineered by looking at the source code.

Some configs I was interested in include:

• Select which example scripts will be run and which will be static. The default pattern for the script to run is DEFAULT_GALLERY_CONF["filename_pattern"] = re.escape(os.sep) + "plot" which runs scripts with name starting in plot. This can be set to anything else by changing the conf dictionary in the gallery_conf.py.
  • Sort the examples. Some sorting methods are defined in mkdocs_gallery/sorting.py. For some inexplicable reason the default sorting method is by number of lines of code. DEFAULT_GALLERY_CONF["within_subsection_order"] = NumberOfCodeLinesSortKey This can be changed to alphabetical order by importing from mkdocs_gallery.sorting import FileNameSortKey in the gallery_conf.py and setting conf"within_subsection_order"] = FileNameSortKey

If you need custom sorting, this can be easily achieved by creating a callable class that returns the sorting function to be used. The sorting happens in the script mkdocs_gallery/gen_data_model.py, within the GalleryBase.collect_script_files method. The method calls,

listdir = sorted(listdir, key=self.conf["within_subsection_order"]())

Where conf is the dictionary of configuration, listdir is a list of pathlib.Path paths. As long as the argument of key is a funciton that takes a path and returns something that can be sorted, you are good to go.

[billbrod]

This sounds super helpful. plotly is a big dependency (and doesn't seem to do anything), do you know why it gets added? And you're not saying we should include it, right?

For the static scripts, where do the outputs come from? Or does it just show the lines of code and that's it (similar to if we included code in a markdown file)? So there'd be no plots?

[BalzaniEdoardo]

about plotly, I am not sure. I am not sure what happens if I don't specify that configuration, not super clear from the mkdocs-gallery documentation