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

Adjust the regex to accept source of a node without a path #24

Merged
merged 1 commit into from
Nov 27, 2024

Conversation

klecki
Copy link
Contributor

@klecki klecki commented Nov 27, 2024

Hi, I appreciate the work done in this extension, I recently integrated it in NVIDIA DALI docs.

In DALI, we generated our main API submodule tree in runtime. We have a nvidia/dali/fn/__init__.py which is the entry point for nvidia.dali.fn API, but submodules like nvidia.dali.fn.decoders don't have corresponding files and are created in runtime (when library is loaded we query the C++ backend for that structure).

When I logged the source member of the sphinx node corresponding to the functions in those modules, for the top level API I get:

node.source='/home/klecki/.local/lib/python3.10/site-packages/nvidia/dali/fn/__init__.py:docstring of nvidia.dali.fn.pad'

but for the submodule I see just:

node.source='docstring of nvidia.dali.fn.decoders.image_slice'

Missing the /path/to/file.py: part (note the : is missing)

I guess it's similar to:

>>> nvidia.dali.fn
<module 'nvidia.dali.fn' from '/home/klecki/.local/lib/python3.10/site-packages/nvidia/dali/fn/__init__.py'>
>>> nvidia.dali.fn.decoders
<module 'nvidia.dali.fn.decoders' (<_frozen_importlib_external._NamespaceLoader object at 0x7fffd67be290>)>

The regex in this line for the missing-reference resolver assumes that the : is there: https://github.com/sqlalchemyorg/sphinx-paramlinks/blob/main/sphinx_paramlinks/sphinx_paramlinks.py#L305

I was able to work around this by creating a missing-reference resolver with higher priority to inject : into the source member before calling the sphinx_paramlinks back: NVIDIA/DALI#5723 - but in the end I realized it's easier to
inject the full absolute reference to the parameter while processing the docstring in autodoc-process-docstring hook: NVIDIA/DALI#5725
(Our autodoc-process-docstring hook detects parameters surrounded by single backticks, checks if they appear in the current object's signature, and if so appends the :paramref: directive ahead of them, allowing more concise Python docstring and clickable links for parameter references in Sphinx).

Although I worked around the problem I still think someone else might hit it, so I propose to relax the regex.

When resolving missing reference a node.source may not contain the
"path/to/file.py:" part (for example if the module is generated at
runtime), but the regex assumed that `:` will be present.

Signed-off-by: Krzysztof Lecki <[email protected]>
@zzzeek
Copy link
Contributor

zzzeek commented Nov 27, 2024

that's fine, thanks!

@zzzeek zzzeek merged commit 2d91347 into sqlalchemyorg:main Nov 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants