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.

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

Improved the API documentation to avoid breaking intersphinx #1638

Merged
merged 5 commits into from
Oct 27, 2022
Merged

Improved the API documentation to avoid breaking intersphinx #1638

merged 5 commits into from
Oct 27, 2022

Conversation

hgrecco
Copy link
Owner

@hgrecco hgrecco commented Oct 26, 2022

  • Closes Intersphinx issue #1637
  • Executed pre-commit run --all-files with no errors
  • The change is fully covered by automated unit tests
  • Documented in docs/ as appropriate
  • Added an entry to the CHANGES file

@hgrecco hgrecco force-pushed the develop branch 5 times, most recently from 48391a3 to 905aaba Compare October 26, 2022 21:33
@hgrecco
Partially reorganized docs
cf3d431 
- api is now split into 3 parts
- files are reorganized in folders

Additionally, some class members (Quantity, Unit, Measurement, Group, Context, System)
are excluded from the docs as they confuse sphinx.
@marscher marscher mentioned this pull request Oct 27, 2022
Closed
@hgrecco hgrecco changed the title Develop Improved the API documentation to avoid breaking intersphinx Oct 27, 2022
@hgrecco hgrecco merged commit 7e82013 into master Oct 27, 2022
@bors bors bot deleted the develop branch October 27, 2022 12:52
@marscher
Copy link
Contributor

Thanks a lot for this quick fix. Just tested with latest on RTD. Now I receive the following:

docstring of pint.quantity.Quantity:1: WA: pint.facets.plain.quantity.Magnitude

@hgrecco
Copy link
Owner Author

hgrecco commented Oct 27, 2022

Have you try referencing pint.Quantity?

@marscher
Copy link
Contributor

Sorry, the error popped up, since I did some evil hacks on __module__!
Now it works like a charm!

@hgrecco
Copy link
Owner Author

hgrecco commented Oct 27, 2022

Just released 0.20.1 fixing this.
Thanks for reporting

@jules-ch
Copy link
Collaborator

Thanks @hgrecco for tackling this

@hgrecco
Copy link
Owner Author

hgrecco commented Oct 27, 2022

Just to leave a note for the future, sphinx does not work well with dynamically generated classes. pint.Quantity, pint.Unit, pint.Measurement, and others are dynamically generated classes based on the UnitRegistry parents. Maybe instead of doing that, we can create them manually and check that the parents are properly organized.

Additionally, sphinx is not very happy with classes defined in other places. That is why I have uses autoclass instead of automodules.

@dopplershift
Copy link
Contributor

Thanks for the fix @hgrecco !

@jules-ch
Copy link
Collaborator

Something weird happened with latest change, Grid links now link to scipy and dask for the getting started & API Reference

@hgrecco
Copy link
Owner Author

hgrecco commented Oct 27, 2022

intersphinx being too clever masquerades an error.

@jules-ch
Copy link
Collaborator

Made a PR for this

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Intersphinx issue
4 participants
@hgrecco @marscher @jules-ch @dopplershift