tessl/pypi-sphinx-codeautolink

Automatic links from code examples to reference documentation.

Overview

Eval results

Files

RST Directives

Name: tessl/pypi-sphinx-codeautolink
Author: tessl

Custom Sphinx directives for controlling link generation behavior, including example display, code concatenation, prefacing, and selective skipping. These directives provide fine-grained control over how the extension processes code blocks in your documentation.

Capabilities

Examples Directive

Display references to code examples for a given object, creating a collapsible table showing where the object appears in documentation code blocks.

# Directive syntax:
# .. autolink-examples:: <object_name>
#    :collapse:
#    :type: <reference_type>

class Examples(Directive):
    """
    Gather and display references in code examples.
    
    Creates a backreference table showing all code examples that use
    the specified object, with links to those examples.
    """
    has_content = False
    required_arguments = 1  # object name
    optional_arguments = 0
    option_spec = {
        "collapse": "flag",     # Make table collapsible 
        "type": "unchanged"     # Reference type (default: "class")
    }

Concatenation Directive

Toggle and control block concatenation in a document, allowing multiple adjacent code blocks to be treated as a single continuous code context.

# Directive syntax:
# .. autolink-concat:: [on|off|section]

class Concat(Directive):
    """
    Toggle and cut block concatenation in a document.
    
    Controls whether adjacent code blocks should be concatenated
    together for analysis, maintaining variable state across blocks.
    """
    has_content = False
    required_arguments = 0
    optional_arguments = 1  # mode: "on", "off", or "section"

Preface Directive

Include preface code in the next code block, allowing you to specify imports or setup code that should be prepended during analysis without displaying it.

# Directive syntax:
# .. autolink-preface:: [level]
#    content lines...

class Preface(Directive):
    """
    Include a preface in the next code block.
    
    Adds setup code (like imports) to code blocks for analysis
    without displaying the preface code in the output.
    """
    has_content = True
    required_arguments = 0
    optional_arguments = 1
    final_argument_whitespace = True
    option_spec = {
        "level": "unchanged"  # "next", "file", etc.
    }

Skip Directive

Skip auto-linking for the next code block or range of content, providing selective control over which code blocks receive automatic linking.

# Directive syntax:
# .. autolink-skip:: [next|section|file|off]

class Skip(Directive):
    """
    Skip auto-linking next code block.
    
    Prevents the extension from processing specified code blocks,
    useful for code that shouldn't have links or causes parsing issues.
    """
    has_content = False
    required_arguments = 0
    optional_arguments = 1  # level: "next", "section", "file", "off"

Directive Node Classes

Internal node classes used to represent directive markers in the document tree.

class DeferredExamples(nodes.Element):
    """
    Deferred node for substitution later when references are known.
    
    Placeholder node that gets replaced with actual backreference
    tables after all code has been analyzed.
    """
    def __init__(self, ref: str, collapse: bool): ...
    def copy(self): ...

class ConcatMarker(nodes.Element):
    """Marker for concatenation directives."""
    def __init__(self, mode: str | None = None): ...
    def copy(self): ...

class PrefaceMarker(nodes.Element):
    """Marker for preface directives."""
    def __init__(self, content: str, level: str): ...
    def copy(self): ...

class SkipMarker(nodes.Element):
    """Marker for skip directives."""
    def __init__(self, level: str): ...
    def copy(self): ...

Visitor for Cleanup

Visitor class for removing directive nodes when the extension is disabled.

class RemoveExtensionVisitor(nodes.SparseNodeVisitor):
    """
    Silently remove all codeautolink directives.
    
    Used when the extension is disabled or not generating HTML output,
    removes directive markers that would otherwise appear as text.
    """
    def unknown_departure(self, node) -> None: ...
    def unknown_visit(self, node) -> None: ...

Usage Examples

Examples Directive Usage

Show where a class or function is used in documentation:

API Reference
=============

.. autoclass:: mymodule.MyClass
   :members:

.. autolink-examples:: mymodule.MyClass
   :collapse:

.. autolink-examples:: mymodule.my_function
   :type: function

Concatenation Control

Control how adjacent code blocks are linked together:

.. autolink-concat:: on

.. code-block:: python
   
   import numpy as np
   data = np.array([1, 2, 3])

.. code-block:: python
   
   # This block sees 'data' from previous block
   result = np.mean(data)
   print(result)

.. autolink-concat:: off

.. code-block:: python
   
   # This block starts fresh - no 'data' variable
   new_data = [4, 5, 6]

Preface Usage

Add hidden setup code for analysis:

.. autolink-preface::
   import matplotlib.pyplot as plt
   import numpy as np

.. code-block:: python
   
   # The preface imports are available but not shown
   x = np.linspace(0, 10, 100)
   plt.plot(x, np.sin(x))
   plt.show()

Section-Level Preface

Apply preface to all code blocks in a section:

.. autolink-preface::
   :level: section
   
   import pandas as pd
   import numpy as np
   
   # Sample data for all examples
   df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})

Basic Operations
----------------

.. code-block:: python
   
   # df is available from section preface
   print(df.head())

.. code-block:: python
   
   # Still available in this block too
   result = df.mean()

Skip Usage

Prevent linking on specific blocks:

.. autolink-skip::

.. code-block:: python
   
   # This code won't get automatic links
   # Useful for pseudocode or broken examples
   somefunction()  # Won't try to link 'somefunction'

.. code-block:: python
   
   # Normal linking resumes here
   import os
   os.path.join('a', 'b')  # 'import', 'os' will be linked

Section-Level Skip

Skip linking for an entire section:

.. autolink-skip:: section

Pseudocode Examples
===================

.. code-block:: python
   
   # No links in this section
   abstract_function()
   
.. code-block:: python
   
   # Also no links here
   another_abstract_call()

Install with Tessl CLI

npx tessl i tessl/pypi-sphinx-codeautolink

docs