Automatic links from code examples to reference documentation

Overview

sphinx-codeautolink

PyPI package License: MIT documentation build status

Automatic links from Python code examples to reference documentation at the flick of a switch! sphinx-codeautolink analyses the code in your documentation and inserts links to definitions that you use.

For a live demo, see our online documentation on Read The Docs.

sphinx-codeautolink elsewhere:

Installation

$ pip install sphinx-codeautolink

To enable sphinx-codeautolink, modify the extension list in conf.py. Note that the extension name uses an underscore rather than a hyphen.

extensions = [
    ...,
    "sphinx_codeautolink",
]

That's it! Now your code examples are linked. For ways of concatenating multiple examples and setting default import statements among other things, have a look at the online documentation.

Comments
  • Option to warn on missing intersphinx config or imports

    Option to warn on missing intersphinx config or imports

    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!

    enhancement 
    opened by DanCardin 22
  • Support for `literalinclude`

    Support for `literalinclude`

    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.

    documentation 
    opened by nwu63 14
  • Build error on RTD

    Build error on RTD

    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.

    bug 
    opened by mgeier 11
  • Automatic support for ipython3 code blocks

    Automatic support for ipython3 code blocks

    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
    opened by mgeier 11
  • 0.4.0: sphinx (4.2.0) warnings on man page build

    0.4.0: sphinx (4.2.0) warnings on man page build

    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!
    
    bug 
    opened by kloczek 9
  • Share mwe for the annotation error

    Share mwe for the annotation error

    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
    opened by OriolAbril 8
  • Don't warn on missing inventory in import statement if import target resolves

    Don't warn on missing inventory in import statement if import target resolves

    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.

    enhancement wontfix 
    opened by DanCardin 7
  • Turn ParsingError exceptions into Sphinx warnings

    Turn ParsingError exceptions into Sphinx warnings

    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.

    enhancement 
    opened by mgeier 7
  • Make the extension parallel_read_safe or declare that it's not

    Make the extension parallel_read_safe or declare that it's not

    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).

    enhancement 
    opened by mgeier 7
  • Add conda forge badge, adjust tox configuration, fix pydocstyle

    Add conda forge badge, adjust tox configuration, fix pydocstyle

    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 :)
    
    opened by Zeitsperre 6
  • Support ipython directive

    Support ipython directive

    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!

    opened by felix-hilden 6
  • Issue with type resolution

    Issue with type resolution

    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.

    bug 
    opened by bryevdv 6
  • Match-case overriding used variable is handled incorrectly

    Match-case overriding used variable is handled incorrectly

    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.

    bug help wanted 
    opened by felix-hilden 0
  • Provide a way to suppress some warnings

    Provide a way to suppress some warnings

    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.

    enhancement 
    opened by felix-hilden 2
  • Track subscripts and multi-assignments by analysing nested type hints

    Track subscripts and multi-assignments by analysing nested type hints

    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.

    enhancement 
    opened by felix-hilden 1
Owner
Felix Hildén
Computer vision and pattern recognition graduate, a past-time programmer.
Felix Hildén
Speed up Sphinx builds by selectively removing toctrees from some pages

Remove toctrees from Sphinx pages Improve your Sphinx build time by selectively removing TocTree objects from pages. This is useful if your documentat

Executable Books 8 Jan 04, 2023
Plover jyutping - Plover plugin for Jyutping input

Plover plugin for Jyutping Installation Navigate to the repo directory: cd plove

Samuel Lo 1 Mar 17, 2022
Sphinx theme for readthedocs.org

Read the Docs Sphinx Theme This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devi

Read the Docs 4.3k Dec 31, 2022
In this Github repository I will share my freqtrade files with you. I want to help people with this repository who don't know Freqtrade so much yet.

My Freqtrade stuff In this Github repository I will share my freqtrade files with you. I want to help people with this repository who don't know Freqt

Simon Kebekus 104 Dec 31, 2022
The sarge package provides a wrapper for subprocess which provides command pipeline functionality.

Overview The sarge package provides a wrapper for subprocess which provides command pipeline functionality. This package leverages subprocess to provi

Vinay Sajip 14 Dec 18, 2022
JMESPath is a query language for JSON.

JMESPath JMESPath (pronounced "james path") allows you to declaratively specify how to extract elements from a JSON document. For example, given this

1.7k Dec 31, 2022
Visualizacao-dados-dell - Repositório com as atividades desenvolvidas no curso de Visualização de Dados

📚 Descrição Neste curso da Dell trabalhamos com a visualização de dados. 🖥️ Aulas 1.1 - Explorando conjuntos de dados 1.2 - Fundamentos de visualiza

Claudia dos Anjos 1 Dec 28, 2021
Sane and flexible OpenAPI 3 schema generation for Django REST framework.

drf-spectacular Sane and flexible OpenAPI 3.0 schema generation for Django REST framework. This project has 3 goals: Extract as much schema informatio

T. Franzel 1.4k Jan 08, 2023
Essential Document Generator

Essential Document Generator Dead Simple Document Generation Whether it's testing database performance or a new web interface, we've all needed a dead

Shane C Mason 59 Nov 11, 2022
Code and pre-trained models for "ReasonBert: Pre-trained to Reason with Distant Supervision", EMNLP'2021

ReasonBERT Code and pre-trained models for ReasonBert: Pre-trained to Reason with Distant Supervision, EMNLP'2021 Pretrained Models The pretrained mod

SunLab-OSU 29 Dec 19, 2022
This programm checks your knowlege about the capital of Japan

Introduction This programm checks your knowlege about the capital of Japan. Now, what does it actually do? After you run the programm you get asked wh

1 Dec 16, 2021
Valentine-with-Python - A Python program generates an animation of a heart with cool texts of your loved one

Valentine with Python Valentines with Python is a mini fun project I have coded.

Niraj Tiwari 4 Dec 31, 2022
Highlight Translator can help you translate the words quickly and accurately.

Highlight Translator can help you translate the words quickly and accurately. By only highlighting, copying, or screenshoting the content you want to translate anywhere on your computer (ex. PDF, PPT

Coolshan 48 Dec 21, 2022
Yu-Gi-Oh! Master Duel translation script

Yu-Gi-Oh! Master Duel translation script

715 Jan 08, 2023
Collections of Beautiful Latex Snippets

HandyLatex Collections of Beautiful Latex Snippets Table 👉 Succinct table with bold separation line and gray text %################## Dependencies ##

Xintao 15 Apr 11, 2022
Spin-off Notice: the modules and functions used by our research notebooks have been refactored into another repository

Fecon235 - Notebooks for financial economics. Keywords: Jupyter notebook pandas Federal Reserve FRED Ferbus GDP CPI PCE inflation unemployment wage income debt Case-Shiller housing asset portfolio eq

Adriano 825 Dec 27, 2022
NetBox plugin for BGP related objects documentation

Netbox BGP Plugin Netbox plugin for BGP related objects documentation. Compatibility This plugin in compatible with NetBox 2.10 and later. Installatio

Nikolay Yuzefovich 133 Dec 27, 2022
DeltaPy - Tabular Data Augmentation (by @firmai)

DeltaPy⁠⁠ — Tabular Data Augmentation & Feature Engineering Finance Quant Machine Learning ML-Quant.com - Automated Research Repository Introduction T

Derek Snow 470 Dec 28, 2022
Python Eacc is a minimalist but flexible Lexer/Parser tool in Python.

Python Eacc is a parsing tool it implements a flexible lexer and a straightforward approach to analyze documents.

Iury de oliveira gomes figueiredo 60 Nov 16, 2022
Documentation of the QR code found on new Austrian ID cards.

Austrian ID Card QR Code This document aims to be a complete documentation of the format used in the QR area on the back of new Austrian ID cards (Per

Gabriel Huber 9 Dec 12, 2022