Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 20 commits into from
Sep 13, 2023

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 added this to In progress in Documentation via automation 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?

doc/htmldoc/_ext/list_examples.py Outdated Show resolved Hide resolved
models/iaf_psc_alpha.h Show resolved Hide resolved
Documentation automation moved this from In progress to Review Aug 15, 2023
@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! 👍

pynest/examples/spatial/conncon_targets.py Outdated Show resolved Hide resolved
pynest/examples/spatial/connex_ew.py Outdated Show resolved Hide resolved
Co-authored-by: Dennis Terhorst <terhorstd@users.noreply.github.com>
@jessica-mitchell jessica-mitchell merged commit a152d21 into nest:master Sep 13, 2023
20 checks passed
Documentation automation moved this from Review to Done Sep 13, 2023
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
Documentation
  
Done
Development

Successfully merging this pull request may close these issues.

None yet

3 participants