Skip to content

Add custom Sphinx extension that lists examples based on model name#2859

Merged
jessica-mitchell merged 20 commits intonest:masterfrom
jessica-mitchell:add-ext-sphinx
Sep 13, 2023
Merged

Add custom Sphinx extension that lists examples based on model name#2859
jessica-mitchell merged 20 commits intonest:masterfrom
jessica-mitchell:add-ext-sphinx

Conversation

@jessica-mitchell
Copy link
Contributor

@jessica-mitchell jessica-mitchell commented Jul 12, 2023

This PR adds a custom Sphinx extension that displays a list of examples based on model name.

How to use it
Add directive to reStructured Text with required argument - the model_name:

.. listexamples:: model_name

This was used in models/iaf_psc_alpha.h and aeif_cond_alpha
See output here

Updated

  • Script now includes function that finds matches of model names in examples
  • The titles of examples are displayed rather than filename
  • Using the ref role syntax, which should allow the use of this directive anywhere in the documentation without issue (hopefully)

TODO

  • Rename some example titles that are unclear
  • Fix sorting so it's used on the titles rather than filenames

@jessica-mitchell jessica-mitchell added T: Enhancement New functionality, model or documentation S: Normal Handle this with default priority labels Jul 12, 2023
@jessica-mitchell jessica-mitchell changed the title Add Sphinx extension that lists examples based on model name Add custom Sphinx extension that lists examples based on model name Jul 13, 2023
Copy link
Contributor

@pnbabu pnbabu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think sorting the list of files by title text rather than the filenames is more useful. I see that it's listed as a TODO in this PR. Is that planned to be addressed here?

@jessica-mitchell
Copy link
Contributor Author

@pnbabu I finally managed to sort the examples by title; this required a fair bit of reworking the extension script so its quite different now

Copy link
Contributor

@pnbabu pnbabu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me! This list is super helpful for someone browsing through the models. I think we could add the directive to all model files once you have approval from other reviewers as well.

Copy link
Contributor

@terhorstd terhorstd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two bytes to cut, then I think it's ready to go.
Thanks for the cool upgrade! 👍

Co-authored-by: Dennis Terhorst <terhorstd@users.noreply.github.com>
@jessica-mitchell jessica-mitchell merged commit a152d21 into nest:master Sep 13, 2023
@jessica-mitchell jessica-mitchell deleted the add-ext-sphinx branch April 24, 2025 07:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S: Normal Handle this with default priority T: Enhancement New functionality, model or documentation

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants

Comments