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

📚 DOCS: Add intersphinx aliases for __all__ imports #5657

Merged
merged 2 commits into from
Sep 23, 2022
Merged

📚 DOCS: Add intersphinx aliases for __all__ imports #5657

merged 2 commits into from
Sep 23, 2022

Conversation

chrisjsewell
Copy link
Member

This PR adds alias objects to python sphinx domain. This allows for any project to reference e.g.
aiida.orm.Data instead of aiida.orm.nodes.data.data.Data (and also works for all methods etc)

@chrisjsewell
📚 DOCS: Add intersphinx aliases for __all__ imports
0d2eaa3 
This PR adds alias objects to python sphinx domain.
This allows for any project to reference e.g.
`aiida.orm.Data` instead of `aiida.orm.nodes.data.data.Data`
(and also works for all methods etc)
@chrisjsewell chrisjsewell linked an issue Sep 22, 2022 that may be closed by this pull request
Docs: Intersphinx references require fully qualified name for 2.0 documentation #5518
Closed
@chrisjsewell
Copy link
Member Author

chrisjsewell commented Sep 22, 2022 •
edited
Loading

supercedes #5569

@chrisjsewell
Copy link
Member Author

chrisjsewell commented Sep 22, 2022 •
edited
Loading

FYI, this YAML file is created directly from the objects.inv, i.e. lists exactly what you can reference using intersphinx (or locally here)

aiida-objects.txt

sphuber
sphuber reviewed Sep 23, 2022
View reviewed changes
Copy link
Contributor

@sphuber sphuber left a comment

Choose a reason for hiding this comment

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

Apart from one comment, looks good to me. Is there a simple way to add a small test for this? Currently we have no idea if this actually works, correct?

docs/source/conf.py Outdated
py: PythonDomain = env.get_domain('py')

shorthands = {}
for modname, module in (('orm', orm),( 'common', common), ('engine', engine), ('plugins', plugins)):
Copy link
Contributor

Choose a reason for hiding this comment

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

Why hardcode these modules? Shouldn't we simply do this for all subpackages of the aiida package?

Copy link
Member Author

Choose a reason for hiding this comment

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

done in 9e23ab9 👍

@chrisjsewell
Copy link
Member Author

Is there a simple way to add a small test for this? Currently we have no idea if this actually works, correct?

You just have to trust my brilliance 😆
But no, I would say the test is the document's build, without this it would fail because you would generate a bunch of warnings about unresolved references (since I removed the lines from the previous AutodocAliases)

@sphuber
Copy link
Contributor

sphuber commented Sep 23, 2022

But no, I would say the test is the document's build, without this it would fail because you would generate a bunch of warnings about unresolved references (since I removed the lines from the previous AutodocAliases)

Fair enough. Fine to leave it without an explicit test then. Are you still looking into my other comment?

@sphuber sphuber self-requested a review September 23, 2022 10:01
sphuber
sphuber approved these changes Sep 23, 2022
View reviewed changes
Copy link
Contributor

@sphuber sphuber left a comment

Choose a reason for hiding this comment

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

Cheers @chrisjsewell

@chrisjsewell chrisjsewell merged commit 3591163 into aiidateam:main Sep 23, 2022
@chrisjsewell chrisjsewell deleted the fix-intersphinx branch September 23, 2022 10:36
This was referenced Sep 23, 2022
Closed
Merged
sphuber pushed a commit that referenced this pull request Sep 23, 2022
@chrisjsewell @sphuber
📚 DOCS: Add intersphinx aliases for __all__ imports (#5657)
8b55a2a 
This commit adds alias objects to the sphinx python domain.
This allows for any project to reference, e.g.
`aiida.orm.Data` instead of `aiida.orm.nodes.data.data.Data`, etc.

Cherry-pick: 3591163
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@sphuber sphuber sphuber approved these changes

@ltalirz ltalirz Awaiting requested review from ltalirz

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Docs: Intersphinx references require fully qualified name for 2.0 documentation
2 participants
@chrisjsewell @sphuber