Skip to content

doc: add pandas and xarray fixtures to testing API docs - #28879

Merged
timhoffm merged 2 commits into
matplotlib:mainfrom
story645:doc-fixtures
Sep 26, 2024
Merged

timhoffm merged 2 commits into
matplotlib:mainfrom
story645:doc-fixtures

Conversation

@story645

Copy link
Copy Markdown
Member

PR summary

Motivated by #28830, figured it'd be a lot easier for contributors to use/reviewers to suggest if the pandas and xarray fixtures were exposed in the docs. I'm not fond of the subheading title but also can't think of a better one.

PR checklist

@story645 story645 added topic: testing Documentation: API files in lib/ and doc/api labels Sep 24, 2024
@timhoffm

Copy link
Copy Markdown
Member

Does not render for some reason.

@story645

Copy link
Copy Markdown
Member Author

it's rendered here, but getting lost:
https://output.circle-artifacts.com/output/job/33765224-5d37-442d-9e80-dfb6348738b2/artifacts/0/doc/build/html/api/testing_api.html#data-container-testing-fixtures

Was wondering if I should maybe add sample usage to the docstrings

@timhoffm

Copy link
Copy Markdown
Member

That's what I meant. For some reason autofunction does not produce content here.

If nothing else helps, you could resort to a manual .. Py::function::. Not preferred to have doc content in rst away from the function, IMHO bearable in this special case.

@story645

Copy link
Copy Markdown
Member Author

Weird cause it works locally:

image

@timhoffm

timhoffm commented Sep 25, 2024 •

Copy link
Copy Markdown
Member

Theory: I suspect the reason is that matplotlib.testing.conftest imports pytest. This fails because pytest is not present in the doc build environment. I know that Sphinx autodoc silently ignores failed package imports and does not produce output in this case.

You may try autodoc_mock_imports but I don't know whether that can mock decorators (if not you will still fail when the import ties to run the @pytest.fixture).

@timhoffm timhoffm left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Mock import works 👍

Was wondering if I should maybe add sample usage to the docstrings

This would be very helpful.

Comment thread doc/api/testing_api.rst Resolved
@timhoffm

Copy link
Copy Markdown
Member

@story645 you can add the usage examples or merge immediately - as you see fit.

@story645

Copy link
Copy Markdown
Member Author

I'm locally building the usage examples, will push in a bit

@story645
story645 force-pushed the doc-fixtures branch 2 times, most recently from 3534879 to 291541a Compare September 25, 2024 21:25
@story645

Copy link
Copy Markdown
Member Author

I so don't understand how it's even more broken now

@timhoffm timhoffm left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

"Example" is not a numpydoc section. It's the plural https://numpydoc.readthedocs.io/en/latest/format.html#examples

Maybe this is tripping up numpydoc/autodoc?

Comment thread lib/matplotlib/testing/conftest.py Resolved
Comment thread lib/matplotlib/testing/conftest.py Resolved
Comment thread lib/matplotlib/testing/conftest.py Resolved
Comment thread lib/matplotlib/testing/conftest.py Resolved
@story645

Copy link
Copy Markdown
Member Author

how would you all feel about more pre-commits: https://numpydoc.readthedocs.io/en/latest/validation.html

@QuLogic

QuLogic commented Sep 26, 2024

Copy link
Copy Markdown
Member

Well, it currently outputs a 27K-line table of issues on just the files in lib/matplotlib/*.py, so I'm not sure how feasible that is right now.

@story645

Copy link
Copy Markdown
Member Author

Well, it currently outputs a 27K-line table of issues on just the files in lib/matplotlib/*.py, so I'm not sure how feasible that is right now.

I know linting fix PRs aren't folks faves, but this seems like a good low hanging fruit task for sprints

Comment thread lib/matplotlib/testing/conftest.py Resolved
Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
@timhoffm
timhoffm merged commit ba05b44 into matplotlib:main Sep 26, 2024
@timhoffm

Copy link
Copy Markdown
Member

I know linting fix PRs aren't folks faves, but this seems like a good low hanging fruit task for sprints

Fine as long as the resulting PRs are trivial to review (small enough, only one kind of change at a time).

I suspect the 27k-lines of issues contain a lot of aspects that we cannot or don't want to fulfill. I think you'd have to start with a checks whitelist to work your way up and not get overwhelmed with messages. Then, when the big chunks are done, switch to the blacklist and narrow down further.

@story645
story645 deleted the doc-fixtures branch September 26, 2024 15:41
kc9323 pushed a commit to kc9323/matplotlib that referenced this pull request Oct 10, 2024
…8879)


Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
@QuLogic QuLogic added this to the v3.10.0 milestone Apr 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Documentation: API files in lib/ and doc/api Documentation: build building the docs topic: testing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants