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

avoid duplicate API documentation for ImageViewer, CollectionViewer #5434

Merged
merged 1 commit into from
Jun 20, 2021

Conversation

grlee77
Copy link
Contributor

@grlee77 grlee77 commented Jun 19, 2021

Recent PRs have been failing on some of the CI jobs due to warnings from Sphinx about duplicate entries in the API docs for CollectionViewer.

It seems that both ImageViewer and CollectionViewer are imported under both skimage.viewer and skimage.viewer.viewers. apigen.py generates API docs for these two classes for both locations and sphinx 4.x raises a warning about this.

As a workaround, this PR removes the skimage.viewer.viewers submodule from the autogenerated API documentation so that there are no longer duplicate occurrences. I'm not sure if there is any better workaround. The warning message generated by sphinx mentions adding :noindex: to one of the instances in the .rst files, but that didn't seem applicable here since the .rst files are autogenerated by the tools/build_modref_templates.py script.

Description

Checklist

For reviewers

  • Check that the PR title is short, concise, and will make sense 1 year
    later.
  • Check that new functions are imported in corresponding __init__.py.
  • Check that new features, API changes, and deprecations are mentioned in
    doc/release/release_dev.rst.

ImageViewer, CollectionViewer are documented both at skimage.viewer and skimage.viewer.viewers
Sphinx 4.x does not like this and raises a warning.
As a workaround, this PR removes the skimage.viewer.viewers submodule from the autogenerated API documentation
@grlee77 grlee77 added 📄 type: Documentation Updates, fixes and additions to documentation 🔧 type: Maintenance Refactoring and maintenance of internals labels Jun 19, 2021
@grlee77
Copy link
Contributor Author

grlee77 commented Jun 20, 2021

This has resolved the CI failures that have been happening this past week

@mkcor
Copy link
Member

mkcor commented Jun 20, 2021

Thank you so much, @grlee77! I find your workaround satisfactory; I briefly looked into the issue and couldn't find a better solution:

The warning message generated by sphinx mentions adding :noindex: to one of the instances in the .rst files, but that didn't seem applicable here since the .rst files are autogenerated by the tools/build_modref_templates.py script.

Indeed.

I guess I can merge this PR even without a second approval, since it's a CI hotfix.

@mkcor mkcor merged commit 4f5a142 into scikit-image:main Jun 20, 2021
@grlee77 grlee77 deleted the api-doc-fix-avoid-duplicate branch July 8, 2021 20:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
📄 type: Documentation Updates, fixes and additions to documentation 🔧 type: Maintenance Refactoring and maintenance of internals
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants