8000 Update layerlist.py docstring to stop doc build warnings by willingc · Pull Request #7660 · napari/napari · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Update layerlist.py docstring to stop doc build warnings #7660

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 1 commit into from
Mar 4, 2025
Merged

Update layerlist.py docstring to stop doc build warnings #7660

merged 1 commit into from
Mar 4, 2025

Conversation

willingc
Copy link
Collaborator

References and relevant issues

Trying ro reduce warnings in docs CI

Description

This PR checks if changing the heading level for events will stop the warning error about the LayerList for every CI run.

@willingc
Update layerlist.py docstring
77c6443 
This PR checks if changing the heading level for events will stop the warning error about the LayerList for every CI run.
@willingc willingc 8000 requested a review from a team as a code owner February 28, 2025 16:18
@willingc
Copy link
Collaborator Author

Cool, the docstring change removed the layer list warning.

@willingc willingc changed the title Update layerlist.py docstring Update layerlist.py docstring to stop doc build warnings Feb 28, 2025
@codecov Codecov
Copy link
codecov bot commented Feb 28, 2025 •
edited
Loading

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.84%. Comparing base (68de9b0) to head (77c6443).
Report is 7 commits behind head on main.

Additional details and impacted files 
@@            Coverage Diff             @@
##             main    #7660      +/-   ##
==========================================
- Coverage   92.88%   92.84%   -0.04%     
==========================================
  Files         630      630              
  Lines       59075    59075              
==========================================
- Hits        54869    54851      -18     
- Misses       4206     4224      +18

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

melissawm
melissawm approved these changes Feb 28, 2025
View reviewed changes
Copy link
Member
@melissawm melissawm left a comment

Choose a reason for hiding this comment

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

🤯 This is awesome! Thank you!!
@melissawm melissawm added ready to merge Last chance for comments! Will be merged in ~24h bugfix PR with bugfix documentation Documentation content and tooling labels Feb 28, 2025
@melissawm melissawm added this to the 0.6.0 milestone Feb 28, 2025
@TimMonko
Copy link
Contributor

@willingc cool! Why in the world does this work?

@willingc
Copy link
Collaborator Author

I don't know with 100% certainty but I noticed in the numpy docstring formats that there were specific top-level categories. I decided to give it a shot to demote the events from a top level category to a second level category. So I believe that the parser only looks at the top level headings to see if they match and assumes any content below the top-level belongs as text to the top-level that precedes it. @TimMonko

@melissawm
Copy link
8000
Member

If you can document this at the numpydoc level I'm sure many folks would be very grateful.

@willingc
Copy link
Collaborator Author

@melissawm Here? or at the numpy docstrings site?

@melissawm
Copy link
Member

Here: numpy/numpydoc#202

psobolewskiPhD
psobolewskiPhD approved these changes Feb 28, 2025
View reviewed changes
Copy link
Member
@psobolewskiPhD psobolewskiPhD left a comment

Choose a reason for hiding this comment

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

Wow! Awesome!
I even triple checked the built docs to make sure! 😉

@psobolewskiPhD
Copy link
Member

This is part of addressing napari/docs#596

@jni
Copy link
Member
jni commented Mar 3, 2025

Huh? My prediction would have been that Events would have been a sub-category of Parameters. Instead, it looks like Parameters and Events are siblings, then Notes is a level above:

CleanShot 2025-03-03 at 14 26 51@2x

Why are Parameters and notes not on the same level? 🤔

tldr I was coming here to suggest that Events should be under Notes and not under Parameters, but now I don't know whether my suggestion makes sense. 😅

@jni jni merged commit 26bc9a9 into main Mar 4, 2025
51 checks passed
@jni jni deleted the willingc-patch-1 branch March 4, 2025 07:36
@github-actions github-actions bot removed the ready to merge Last chance for comments! Will be merged in ~24h label Mar 4, 2025
@melissawm
Copy link
Member
melissawm commented Mar 5, 2025 •
edited
Loading

TBF I don't know if napoleon would support that directly - as far as I understand the custom sections need to be params_style or returns_style and so I assume those are the levels where you can fit those custom sections (see https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_custom_sections)

Nevermind - maybe that is what the generic section is about? I haven't tested it directly though.

@willingc willingc mentioned this pull request Mar 11, 2025
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@melissawm melissawm melissawm approved these changes

@psobolewskiPhD psobolewskiPhD psobolewskiPhD approved these changes

Assignees
No one assigned
Labels
bugfix PR with bugfix documentation Documentation content and tooling
Projects
None yet
Milestone
0.6.0
Development

Successfully merging this pull request may close these issues.
5 participants
@willingc @TimMonko @melissawm @psobolewskiPhD @jni
0