DOC: In search for the matplotlib codex

The codex

The matplotlib search tells us about the "codex":

If you want to limit your search to working code examples, include the keyword "codex" (mnemonic for code example) in your search, e.g., "codex ellipse"; see search examples.

and the FAQ: Search examples

The nearly 300 code Gallery included with the Matplotlib source distribution are full-text searchable from the Search Page page, but sometimes when you search, you get a lot of results from the The Matplotlib API or other documentation that you may not be interested in if you just want to find a complete, free-standing, working piece of example code. To facilitate example searches, we have tagged every code example page with the keyword codex for code example which shouldn’t appear anywhere else on this site except in the FAQ. So if you want to search for an example that uses an ellipse, Search Page for codex ellipse.

The problem

Yet, the codex has disappeared from the gallery - probably due to the migration to sphinx-gallery.

In older versions, this looked like

Possible solutions

Remove all references to "codex", as it's more than confusing to be told to look for something that doesn't exist.
Revive the codex by
- manually adding it to all examples
- check in how far some kind of template can be used for this.

The latter would be related to

Examples not shown in API docs for many methods. Examples not shown in API docs for many methods. #10974
DOC: add links to examples for a few examples DOC: add links to examples for a few examples #11019

This seems like something we should be able to inject via sphinx gallery...

As I see it, the gallery example html pages are generated by sphinx from .rst files. Those .rst files are generated by sphinx-gallery from the .py files in the examples folder. The generation of those files happens internally by sphinx-gallery, based on formatted strings.

Options:

Changing the indivudial example .py files. Cumbersome. ❌
Siingle sidedly manipulating the source of spinx-gallery. Out of question. ❌
Monkey-patching the format strings of sphinx-gallery. Would work. ✔️
Injecting the keyword via css. Would produce the desired html output, but not affect seach. ❌
Solve this in the most general way by negotiating and doing PR to Sphinx-Gallery. ❔
Advising the user to search for "Sphinx-Gallery <search text>", instead of "codex <search text>" Works. ✔️

Or did I miss anything? Which options would be worth pursuing here?

Monkey patching would look as follows. Inside of conf.py you'd add something like this:

from sphinx_gallery import gen_rst
gen_rst.SPHX_GLR_SIG = """\n
.. only:: html

 .. rst-class:: sphx-glr-signature

    Keywords: Matplotlib code example, Codex\n"""

Is this the way to go here?

Since I didn't get any answer here I implemented the monkey-patching solution in #11169.

Navigation Menu

Repository navigation

DOC: In search for the matplotlib codex #11151

The codex

The problem

Possible solutions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

DOC: In search for the matplotlib codex #11151

Description

The codex

The problem

Possible solutions

Activity

tacaswell commented on May 1, 2018

ImportanceOfBeingErnest commented on May 2, 2018

ImportanceOfBeingErnest commented on May 2, 2018

ImportanceOfBeingErnest commented on May 4, 2018

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions