I saw your post on reddit and tried applying it to on of my projects, great plugin!

It's finding a bunch of places where my code examples are either incomplete or missing intersphinx setup. It's the going through and finding all my code examples and trying to click on things that is somewhat tedious.

What would be great is if there was an option to emit warnings where this plugin sees code that it wants to link but can't resolve it. That way I could just run it once and go through and fix all the broken code.

Again, great plugin! Works great!

Thanks for this extention! It looks super neat.

In our documentation, we mainly use literainclude blocks instead of having the code directly in the RST file, so that standalone Python scripts in the repo be run without needing to copy/paste. I was wondering if it's possible to support these blocks in addition to code blocks.

Here's the log: https://readthedocs.org/projects/nbsphinx/builds/16789989/

Here's the error:

  File "/home/docs/checkouts/readthedocs.org/user_builds/nbsphinx/envs/latest/lib/python3.7/site-packages/sphinx_codeautolink/extension/__init__.py", line 138, in merge_environments
    env.sphinx_codeautolink_transforms.update(
AttributeError: 'BuildEnvironment' object has no attribute 'sphinx_codeautolink_transforms'

Note that this happens on the second Sphinx call.

My main goal is to use this extension together with https://nbsphinx.readthedocs.io/ and to make it as easy as possible for others to do so as well.

#75 already helped to avoid having to specify custom CSS classes and this PR avoids having to specify codeautolink_custom_blocks.

For reference, here are some changes on the nbsphinx side: https://github.com/spatialaudio/nbsphinx/pull/613 https://github.com/spatialaudio/nbsphinx/pull/614

With those changes in place, the only thing that users have to do is to add 'sphinx_codeautolink' to extensions. And that's exactly the amount they should have to do (i.e. I don't want to enable it automatically when loading nbsphinx).

• [x] Tests written and passed
• [x] Documentation and changelog entry written, docs build passed
• [x] All tox checks passed

Looks like on generate module documentation is failing and prints some warnings

[[email protected] sphinx-codeautolink-0.4.0]$ /usr/bin/python3 setup.py build_sphinx -b man --build-dir build/sphinx
running build_sphinx
Running Sphinx v4.2.0
making output directory... done
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://matplotlib.org/stable/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 7 added, 0 changed, 0 removed
reading sources... [100%] release_notes
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/tkloczko/rpmbuild/BUILD/sphinx-codeautolink-0.4.0/docs/src/404.rst: WARNING: document isn't included in any toctree
done
writing... sphinx-codeautolink.1 { release_notes reference about examples example_library } failed

Exception occurred:
  File "/usr/lib/python3.8/site-packages/sphinx/writers/manpage.py", line 467, in unknown_visit
    raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
NotImplementedError: Unknown node: PrefaceMarker
The full traceback has been saved in /tmp/sphinx-err-0zz69rdx.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

Related to https://github.com/felix-hilden/sphinx-codeautolink/discussions/44. I tracked the error down to the presence of np.random.<distribution> type function calls.

• [ ] Tests written and passed
• [ ] Documentation and changelog entry written, docs build passed
• [ ] All tox checks passed

Issue

Example given below. Generally, it seems that many modules or packages will erroneously warn, presumably when they dont have dedicated pages.

In the below example, sqlalchemy.ext.declarative resolves and is clickable, as it brings you to the correctly annotated page.

Versus from sqlalchemy.orm import declarative_base where sqlalchemy.orm has no corresponding page and warngs, but declarative_base resolves correctly.

Expected behavior

Perhaps for successfully resolved imported items, the package or module in which it resides should not warn if there's no corresponding link for it.

That still leaves import sqlalchemy. Naively i might expect that to link to the root of the docs if there's otherwise no resolved link for it.

Steps to reproduce

Although, and this may still be user error, I'm seeing:

docs/source/experimental_tests.rst:69: WARNING: Inventory missing `sqlalchemy` when resolving `sqlalchemy` on line 1
docs/source/experimental_tests.rst:69: WARNING: Inventory missing `sqlalchemy` when resolving `sqlalchemy` on line 2
docs/source/experimental_tests.rst:69: WARNING: Inventory missing `sqlalchemy.ext.declarative.declarative_base` when resolving `declarative_base` on line 3
WARNING: Cannot locate modules: ..., 'sqlalchemy'

for

.. code-block:: python

   import sqlalchemy
   from sqlalchemy import Column, types
   from sqlalchemy.ext.declarative import declarative_base
   from sqlalchemy.orm import declarative_base  # or this

with

intersphinx_mapping = {
    "sqlalchemy": ("https://docs.sqlalchemy.org/en/14", None),
    ...

Column, types, sqlalchemy.ext.declarative, and the 2nd declarative_base are clickable.

I have some code blocks that intentionally contain syntactically incorrect Python code (https://nbsphinx.readthedocs.io/en/0.8.7/allow-errors.html).

Right now, when using the sphinx_codeautolink extension, I'm getting an extension error.

This is of course very good in most cases, because it allows us to detect mistakes. However, I would like to be able to ignore this in some cases. This would be possible if those errors would be turned into Sphinx warnings. And if those warnings have a type and subtype, they can be ignored while other warnings would still be active.

I think this would be consistent with similar errors like e.g. illegal reStructuredText syntax, which don't stop Sphinx processing and produce warnings instead.

BTW, warnings can easily be turned into errors with the -Wflag.

This extension should use parallel_read_safe to tell Sphinx whether it can be used to read source files in parallel.

See https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata.

Issue

When running Sphinx with the -j option (https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-j), it shows a warning about the sphinx_codeautolink extension not specifying whether it supports parallel operation and therefore Sphinx doesn't do anything in parallel.

Expected behavior

Ideally, the extension should work for parallel builds (there might be some changes necessary?) and should set parallel_read_safe to True.

If that's not possible, it should set parallel_read_safe to False to avoid the Sphinx warning.

Steps to reproduce

Run Sphinx with -j4 (or whatever number > 1).

Closes #111

• [x] Tests written and passed
• [x] Documentation and changelog entry written, docs build passed
• [x] All tox checks passed

Hey there, this PR does the following:

• Adds a conda-forge badge to a few places in the documentation
• Adjusts the pyproject.toml and tox configurations to ensure that $ tox runs properly
• Fixes the code coverage reporting configuration

End results:

  flake8: commands succeeded
  doc8: commands succeeded
  pydocstyle: commands succeeded
  coverage: commands succeeded
  congratulations :)

Related issue: #91

• [x] Tests written and passed
• [x] Documentation and changelog entry written, docs build passed
• [x] All tox checks passed

@OriolAbril could you review this, and particularly comment on your original regex. It had \s*In\s*[...]\s, so is there a situation where the notebook has multiple (or other) spaces there? I just used ^In [...].

@mgeier you've been involved with the other IPython stuff, so your review would be most helpful too!

Issue

When building the Bokeh docs, things expode:

Traceback (most recent call last):
  File "/Users/bryan/anaconda/envs/dev-311/lib/python3.11/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bryan/anaconda/envs/dev-311/lib/python3.11/site-packages/sphinx_codeautolink/extension/__init__.py", line 42, in wrapper
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bryan/anaconda/envs/dev-311/lib/python3.11/site-packages/sphinx_codeautolink/extension/__init__.py", line 176, in create_references
    self.filter_and_resolve(transforms, skipped, doc)
  File "/Users/bryan/anaconda/envs/dev-311/lib/python3.11/site-packages/sphinx_codeautolink/extension/__init__.py", line 200, in filter_and_resolve
    key = resolve_location(name, self.inventory)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bryan/anaconda/envs/dev-311/lib/python3.11/site-packages/sphinx_codeautolink/extension/resolve.py", line 36, in resolve_location
    cursor = locate_type(cursor, tuple(comps), inventory)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bryan/anaconda/envs/dev-311/lib/python3.11/site-packages/sphinx_codeautolink/extension/resolve.py", line 92, in locate_type
    for val in previous.value.mro():
               ^^^^^^^^^^^^^^^^^^^^
TypeError: unbound method type.mro() needs an argument

The proximate cause turns out to be that previous.value is builtins.type at this point:

(Pdb) previous
Cursor(location='builtins.type', value=<class 'type'>, instance=False)

Bokeh is a cross-runtime library and uses a fair amount of meta-programming to automate management of that complexity. That might be why this unexpected values ends up here.

Expected behavior

Completed successful build

Steps to reproduce

I am a maintainer for Bokeh and encountered this while building the Bokeh docs. I am afraid I have not been able to isolate a simpler MRE. Dev guide for building Bokeh docs is here:

https://docs.bokeh.org/en/latest/docs/dev_guide/documentation.html#setting-up-and-building-bokeh-s-documentation

environment:

pydata-sphinx-theme       0.9.0                    pypi_0    pypi
sphinx                    5.3.0                    pypi_0    pypi
sphinx-codeautolink       0.12.1                   pypi_0    pypi
sphinx-copybutton         0.5.0                    pypi_0    pypi
sphinx-design             0.3.0                    pypi_0    pypi
sphinxcontrib-applehelp   1.0.2                    pypi_0    pypi
sphinxcontrib-devhelp     1.0.2                    pypi_0    pypi
sphinxcontrib-htmlhelp    2.0.0                    pypi_0    pypi
sphinxcontrib-jsmath      1.0.1                    pypi_0    pypi
sphinxcontrib-qthelp      1.0.3                    pypi_0    pypi
sphinxcontrib-serializinghtml 1.1.5                    pypi_0    pypi
sphinxext-opengraph       0.7.2                    pypi_0    pypi

Patch?

Changing the condition in resolve.py to exclude type allows the build to complete "successfully":

        if isclass(previous.value) and previous.value is not type and cursor.location not in inventory:

however then there are hundreds of other warnings, so this does not seem like a complete solution:

.. autolink-examples:: bokeh.plotting.figure.ref :collapse:.
None:4:<autosummary>:1: ERROR: Error in "autolink-examples" directive:
maximum 1 argument(s) allowed, 2 supplied.

.. autolink-examples:: bokeh.plotting.figure.plot :collapse:.
None:4:<autosummary>:1: ERROR: Error in "autolink-examples" directive:
maximum 1 argument(s) allowed, 2 supplied.

.. autolink-examples:: bokeh.plotting.figure.coordinates :collapse:.
/Users/bryan/work/bokeh/src/bokeh/plotting/_figure.py:docstring of bokeh.plotting._figure.figure:1: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Without auto-link extension the doc build is 100% warning clean.

When implementing match support in #110 I ran into very hard to navigate issues, which led me to introduce two X-fails to the test suite. The problem is:

Match statements reference and assign multiple values simultaneously. This violates our assumptions quite profoundly, since references and assignments are handled entirely sequentially and generating references relies on the value being assigned in "scope". What's more, the whole nested match is "executed" at once.

I experimented with delaying assignments, effectively generating batches. But it was unsuccessful. I suspect to get this to work, we'll have to either change our architecture significantly, or write a custom assignment handler just for match.

From #103: it could be annoying to deal with e.g. missing inventory warnings when a package and its documentation is out of your reach. But having warnings is still beneficial. I can see a couple of options that we could consider:

• Provide a directive for suppressing warnings in a specific code example: this would mask other warnings in that code example though.
• Provide configuration to disable extra warnings on intersphinx packages: this will surely mask lots of other warnings as well, and doesn't address the fact that you might not want to define a ref for each local module that can be imported.

Any other options? Personally I don't much care for either, but if I had to pick one it would be suppressing specific examples. At least that way people know that they might have problems and have more manual control over it.

From #5: we have the machinery in place to track subscripts and unpacking assignments by analysing type hints that are nested tuples or lists of simple types:

class A:
    attr: int = 3

def foo() -> List[A]:
    pass

def bar() -> Tuple[A, A]:
    pass

# example code
a = lib.foo()[0]
a.attr  # properly linked
b, c = lib.bar()  # b and c linked to A

I'm not sure what to do with other than constant integer subscripts though.