sphinx-codeautolink 0.16.2__tar.gz → 0.17.1__tar.gz

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/MANIFEST.in

@@ -1,6 +1,7 @@
 graft docs
 prune docs/build
 graft requirements
+graft src
 graft tests
 include contributing.rst readme_pypi.rst tox.ini
 global-exclude *.py[cod] __pycache__ *.so

{sphinx_codeautolink-0.16.2/src/sphinx_codeautolink.egg-info → sphinx_codeautolink-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinx-codeautolink
-Version: 0.16.2
+Version: 0.17.1
 Summary: Automatic links from code examples to reference documentation.
 Author-email: Felix Hildén <felix.hilden@gmail.com>
 Maintainer-email: Felix Hildén <felix.hilden@gmail.com>
@@ -70,7 +70,6 @@ sphinx-codeautolink can be installed from the following sources:
 .. code:: sh
 
     $ pip install sphinx-codeautolink
-    # or, alternatively:
     $ conda install -c conda-forge sphinx-codeautolink
 
 Note that the library is in early development, so version pinning is advised.
@@ -85,9 +84,9 @@ Note that the extension name uses an underscore rather than a hyphen.
    ]
 
 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.
+For ways of concatenating examples, setting default import statements,
+or customising link style among other things,
+see the `online documentation <https://sphinx-codeautolink.rtfd.org>`_.
 
 .. |pyversions| image:: https://img.shields.io/pypi/pyversions/sphinx-codeautolink
    :alt: Python versions

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/contributing.rst

@@ -85,6 +85,18 @@ upload manually to `TestPyPI <https://test.pypi.org>`_ instead.
     $ twine upload --repository testpypi dist/*
     $ pip install --index-url https://test.pypi.org/simple/ sphinx-codeautolink
 
+Translations
+------------
+You are also welcome to contribute translations!
+Use the following Babel commands to add new translations and locales.
+
+.. code:: sh
+
+    $ cd src/sphinx_codeautolink
+    $ pybabel init --input-file=locale/sphinx-codeautolink.pot --domain=sphinx-codeautolink --output-dir=locale --locale=fi_FI
+    $ pybabel update --input-file=locale/sphinx-codeautolink.pot --domain=sphinx-codeautolink --output-dir=locale
+    $ pybabel compile --directory=locale --domain=sphinx-codeautolink
+
 .. |issue_resolution| image:: http://isitmaintained.com/badge/resolution/felix-hilden/sphinx-codeautolink.svg
    :target: https://isitmaintained.com/project/felix-hilden/sphinx-codeautolink
    :alt: issue resolution time

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/docs/src/about.rst

@@ -18,7 +18,7 @@ Caveats
 -------
 - **Only works with HTML documentation**, disabled otherwise. If the extension
   is off, it silently removes directives that would produce output.
-- **Only processes literal blocks, not inline code**. Sphinx has great tools
+- **Only processes blocks, not inline code**. Sphinx has great tools
   for linking definitions inline, and longer code should be in a block anyway.
 - **Doesn't run example code**. Therefore all possible resolvable types are not
   found, and the runtime correctness of code cannot be validated.

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/docs/src/conf.py

@@ -56,6 +56,9 @@ plot_formats = [("png", 90)]
 plot_html_show_formats = False
 plot_html_show_source_link = False
 
+html_static_path = ["static"]
+html_css_files = ["custom.css"]
+
 
 def setup(app) -> None:
     app.add_object_type(

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/docs/src/examples.rst

@@ -21,10 +21,16 @@ be analysed and linked to known reference documentation entries.
 
 Different import styles are supported, along with all Python syntax.
 Star imports might be particularly handy in code examples.
-`Doctest <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
-#doctest-blocks>`_ and console blocks using :code:`.. code:: pycon` work too.
-Including code via :rst:dir:`literalinclude` requires using a
-:code:`:language: py` parameter.
+
+A number of other types of blocks are also supported
+along with standard Sphinx configuration, like:
+
+- Literal blocks, the ``.. highlight::`` directive
+  and ``highlight_language`` configuration
+- `Doctest blocks <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks>`_
+- Console blocks using :code:`.. code:: pycon`
+- Including code via :rst:dir:`literalinclude`, but requires using one of the
+  `Python Lexers <https://pygments.org/docs/lexers/#pygments.lexers.python.PythonLexer>`_
 
 .. code:: pycon
 
@@ -39,7 +45,9 @@ particularly in the reference documentation itself:
 
 .. autolink-examples:: lib.Knight
 
-Such a table is generated with :rst:dir:`autolink-examples`::
+Such a table is generated with :rst:dir:`autolink-examples`:
+
+.. code-block:: rst
 
    .. autolink-examples:: lib.Knight
 
@@ -54,14 +62,18 @@ The import can be hidden instead.
 
   lib.Knight().taunt()
 
-The previous block is produced with :rst:dir:`autolink-preface`::
+The previous block is produced with :rst:dir:`autolink-preface`:
+
+.. code-block:: rst
 
    .. autolink-preface:: import lib
    .. code:: python
 
         lib.Knight().taunt()
 
-A multiline preface can be written in the content portion of the directive::
+A multiline preface can be written in the content portion of the directive:
+
+.. code-block:: rst
 
    .. autolink-preface::
 
@@ -90,7 +102,9 @@ the previous left off.
        print(knight.taunt())
        knight.scratch()
 
-This was achieved with :rst:dir:`autolink-concat`::
+This was achieved with :rst:dir:`autolink-concat`:
+
+.. code-block:: rst
 
    .. autolink-concat:: section
    .. code:: python
@@ -118,7 +132,9 @@ and preventing it from being included in further sources with concatenation.
    import lib
    lib.Knight()
 
-Which is done via :rst:dir:`autolink-skip`::
+Which is done via :rst:dir:`autolink-skip`:
+
+.. code-block:: rst
 
    .. autolink-skip::
    .. code:: python
@@ -190,7 +206,9 @@ Reference tables across intersphinx work too:
 It seems that the reference type information is more important
 for Sphinx when dealing with external modules,
 likely because the references cannot be resolved dynamically.
-Please specify a ``type`` in :rst:dir:`autolink-examples`::
+Please specify a ``type`` in :rst:dir:`autolink-examples`:
+
+.. code-block:: rst
 
    .. autolink-examples:: numpy.linspace
       :type: func
@@ -294,12 +312,12 @@ For example, a transformer could be implemented as follows:
 Sometimes links with third-party code blocks are broken.
 See :ref:`about` for a potential solution.
 
+.. _examples-css:
+
 Custom link styles
 ------------------
 If you want a specific style to be applied to code block links,
 you may add your own CSS file to the Sphinx build.
-All code block links use the ``sphinx-codeautolink-a`` class.
-For example, you can add dotted lines to all links and change the hover colour:
 
 .. code:: python
 
@@ -307,12 +325,17 @@ For example, you can add dotted lines to all links and change the hover colour:
    html_static_path = ['static']
    html_css_files = ['custom.css']
 
+To include only in specific documents, see the ``html-page-context`` event
+and the :meth:`Sphinx.add_css_file` function.
+For example, you can add similar underlines as this documentation
+and change the hover colour:
+
 .. code:: css
 
    /* static/custom.css */
    .sphinx-codeautolink-a{
-       border-bottom-color: rgb(0, 0, 0);
-       border-bottom-style: dotted;
+       border-bottom-color: #ccc;
+       border-bottom-style: solid;
        border-bottom-width: 1px;
    }
    .sphinx-codeautolink-a:hover{

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/docs/src/index.rst

@@ -5,7 +5,7 @@ sphinx-codeautolink
 sphinx-codeautolink makes code examples clickable by inserting links
 from individual code elements to the corresponding reference documentation.
 We aim for a minimal setup assuming your examples are already valid Python.
-Click any names in the example below for a demonstration:
+Click any undelined name in the example below for a demonstration:
 
 .. code:: python
 
@@ -42,7 +42,6 @@ sphinx-codeautolink can be installed from the following sources:
 .. code:: sh
 
     $ pip install sphinx-codeautolink
-    # or, alternatively:
     $ conda install -c conda-forge sphinx-codeautolink
 
 To enable sphinx-codeautolink, modify the extension list in ``conf.py``.
@@ -56,8 +55,8 @@ Note that the extension name uses an underscore rather than a hyphen.
    ]
 
 That's it! Now your code examples are linked.
-For ways of concatenating multiple examples
-and setting default import statements among other things,
+For ways of concatenating examples, setting default import statements,
+or customising link style among other things,
 have a look at the :ref:`reference` documentation.
 
 sphinx-codeautolink elsewhere:
@@ -70,7 +69,7 @@ Caveats
 For a more thorough explanation, see :ref:`about`.
 
 - Only works with HTML documentation
-- Only processes literal blocks, not inline code
+- Only processes blocks, not inline code
 - Doesn't run example code
 - Parsing and type hint resolving is incomplete
 

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/docs/src/reference.rst

@@ -14,12 +14,12 @@ Configuration
 -------------
 .. confval:: codeautolink_autodoc_inject
 
-   Type: ``bool``. Inject a :rst:dir:`autolink-examples` table
+   Type: ``bool``. Inject an :rst:dir:`autolink-examples` table
    to the end of all autodoc definitions. Defaults to :code:`False`.
 
 .. confval:: codeautolink_global_preface
 
-   Type: ``str``. Include a :rst:dir:`autolink-preface` before all blocks.
+   Type: ``str``. Include an :rst:dir:`autolink-preface` before all blocks.
    When other prefaces or concatenated sources are used in a block,
    the global preface is included first and only once.
 
@@ -57,14 +57,27 @@ Configuration
 
 .. confval:: codeautolink_warn_on_missing_inventory
 
-   Type: ``bool``. Issue warning when an object cannot be found in
+   Type: ``bool``. Warn when an object cannot be found in
    the inventory (autodoc or intersphinx). Defaults to :code:`False`.
 
 .. confval:: codeautolink_warn_on_failed_resolve
 
-   Type: ``bool``. Issue warning when failing to resolve the canonical location
+   Type: ``bool``. Warn when failing to resolve the canonical location
    of an object that a code element references. Defaults to :code:`False`.
 
+.. confval:: codeautolink_warn_on_no_backreference
+
+   Type: ``bool``. Warn when no backreference could be found
+   from reference documentation using the :rst:dir:`autolink-examples` table.
+   This highlights objects for which no tutorial, example or how-to exists.
+   Defaults to :code:`False`.
+
+.. confval:: codeautolink_warn_on_default_parse_fail
+
+   Type: ``bool``. Warn when a code block using the ``default`` lexer
+   cannot be parsed as Python. By default these cases are ignored by the
+   syntax highlighter, so we match the behavior. Defaults to :code:`False`.
+
 Directives
 ----------
 .. rst:directive:: .. autolink-examples:: object
@@ -89,7 +102,7 @@ Directives
 
 .. rst:directive:: .. autolink-concat:: [mode]
 
-   Toggle literal block concatenation.
+   Toggle block concatenation.
    Concatenated code blocks are treated as a continuous source,
    so that imports and statements in previous blocks affect later blocks.
    Concatenation is begun at the directive, not applied retroactively.
@@ -104,18 +117,32 @@ Directives
 
 .. rst:directive:: .. autolink-preface:: [code]
 
-   Include a hidden preface in the next code block.
-   The next block consumes this directive even if it is not
-   processed (e.g. non-Python blocks) to avoid placement confusion.
+   Include a hidden preface before a code block.
    A multiline preface can be written in the content portion of the directive.
-   Prefaces are included in block concatenation.
+   Prefaces are preserved in block concatenation, and are added to the source
+   in the following order: :confval:`codeautolink_global_preface` > file preface
+   > :rst:dir:`autolink-concat` sources (with their block prefaces)
+   > block prefaces > block source.
+
+   .. rubric:: Options
+
+   .. rst:directive:option:: level
+      :type: preface level
+
+      - "next" - add preface only to the next block (default).
+        Multiple prefaces are combined, and the next block consumes this
+        directive even if it's not processed (e.g. non-Python blocks)
+        to avoid placement confusion.
+      - "file" - set a preface for all blocks in the current file, placed
+        after  but before block-level
+        prefaces.
 
 .. rst:directive:: .. autolink-skip:: [level]
 
    Skip sphinx-codeautolink functionality.
    ``level``, if specified, must be one of:
 
-   - "next" - next block (default)
+   - "next" - next encountered block (default)
    - "section" - blocks until the next title
    - "file" - all blocks in the current file
    - "off" - turn skipping off
@@ -124,10 +151,16 @@ Directives
    it is not processed (e.g. non-Python blocks) to avoid placement confusion.
    Skipped blocks are ignored in block concatenation as well, and concatenation
    is resumed without breaks after skipping is over.
+   "Next" doesn't need to be specified right before the block that would consume
+   it. For e.g. literal blocks the skip directive would be inserted before the
+   preceding paragraph.
 
 CSS class
 ---------
 The CSS class used in all code block links is ``sphinx-codeautolink-a``.
+By default, the links only have a light blue hover colour.
+The style has been made more obvious in the documentation for demonstration.
+See :ref:`examples-css` for more information.
 
 Cleanup functions
 -----------------

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/docs/src/release_notes.rst

@@ -8,6 +8,35 @@ These release notes are based on
 sphinx-codeautolink adheres to
 `Semantic Versioning <https://semver.org>`_.
 
+0.17.1 (2025-02-24)
+-------------------
+- Add translations via i18n (:issue:`164`)
+- Fix attribute and call after walrus leading parser error (:issue:`174`)
+- Fix parsing error in doctest blocks with empty lines (:issue:`176`)
+- Improve error message on uncaught parsing errors (:issue:`177`)
+- Add ``level`` argument to :rst:dir:`autolink-preface` to support
+  file-level prefaces (:issue:`180`)
+
+0.17.0 (2025-02-18)
+-------------------
+Added
+*****
+- Add more Pygments lexer aliases in code blocks (:issue:`160`)
+- Introduce :confval:`codeautolink_warn_on_no_backreference` to highlight
+  where reference documentation does not appear to have
+  a corresponding tutorial or how-to (:issue:`161`)
+- Support the ``default`` lexer, literal blocks, ``.. highlight::`` directive
+  and ``highlight_language`` configuration (:issue:`166`)
+- Add :confval:`codeautolink_warn_on_default_parse_fail` to warn about
+  failing to link code blocks without a language parameter (:issue:`166`)
+- Detect and implicitly use ``pycon`` lexer for blocks that look like
+  console code (:issue:`168`)
+
+Fixed
+*****
+- Fix undocumented class attribute leading to a crash (:issue:`165`)
+- Fix skipping blocks with identical content to linked ones (:issue:`172`)
+
 0.16.2 (2025-01-16)
 -------------------
 - Fix regression in not handling malformed return types (:issue:`159`)

sphinx_codeautolink-0.17.1/docs/src/static/custom.css

@@ -0,0 +1,5 @@
+.sphinx-codeautolink-a{
+    border-bottom-color: #ccc;
+    border-bottom-style: solid;
+    border-bottom-width: 1px;
+}

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/pyproject.toml

@@ -75,6 +75,7 @@ extend-ignore = [
     "COM812", # recommended by ruff format
     "ISC001", # recommended by ruff format
     "PLR0913", # many arguments is fine
+    "PLR0915", # many statements is fine
 ]
 extend-unsafe-fixes = ["F401"]
 isort.split-on-trailing-comma = false
@@ -88,6 +89,7 @@ isort.split-on-trailing-comma = false
     "ANN", # annotations
     "S101", # assertions - necessary in tests
     "T201", # print - helpful in tests
+    "PLR2004", # magic number
 ]
 # TODO: support future annotated hints properly
 "tests/extension/src/test_project/__init__.py" = ["FA100"]

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/readme_pypi.rst

@@ -16,7 +16,6 @@ sphinx-codeautolink can be installed from the following sources:
 .. code:: sh
 
     $ pip install sphinx-codeautolink
-    # or, alternatively:
     $ conda install -c conda-forge sphinx-codeautolink
 
 Note that the library is in early development, so version pinning is advised.
@@ -31,9 +30,9 @@ Note that the extension name uses an underscore rather than a hyphen.
    ]
 
 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.
+For ways of concatenating examples, setting default import statements,
+or customising link style among other things,
+see the `online documentation <https://sphinx-codeautolink.rtfd.org>`_.
 
 .. |pyversions| image:: https://img.shields.io/pypi/pyversions/sphinx-codeautolink
    :alt: Python versions

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/src/sphinx_codeautolink/__init__.py

@@ -1,11 +1,14 @@
 """Sphinx extension for linking code examples to reference documentation."""
 
+from pathlib import Path
+
 from sphinx.application import Sphinx
 
 from .extension import SphinxCodeAutoLink, backref, directive
 from .extension.block import clean_ipython, clean_pycon
+from .extension.translation import MESSAGE_CATALOG_NAME
 
-__version__ = "0.16.2"
+__version__ = "0.17.1"
 
 
 def setup(app: Sphinx):
@@ -43,6 +46,18 @@ def setup(app: Sphinx):
         rebuild="html",
         types=[bool],
     )
+    app.add_config_value(
+        "codeautolink_warn_on_no_backreference",
+        default=False,
+        rebuild="html",
+        types=[bool],
+    )
+    app.add_config_value(
+        "codeautolink_warn_on_default_parse_fail",
+        default=False,
+        rebuild="html",
+        types=[bool],
+    )
 
     app.add_directive("autolink-concat", directive.Concat)
     app.add_directive("autolink-examples", directive.Examples)
@@ -64,4 +79,8 @@ def setup(app: Sphinx):
     app.add_node(
         backref.SummaryNode, html=(backref.visit_summary, backref.depart_summary)
     )
+
+    locale_dir = Path(__file__).resolve().parent / "locale"
+    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
+
     return {"version": __version__, "env_version": 1, "parallel_read_safe": True}

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/src/sphinx_codeautolink/extension/__init__.py

@@ -74,6 +74,9 @@ class SphinxCodeAutoLink:
         self.inventory_map: dict[str, str] = {}
         self.warn_missing_inventory = None
         self.warn_failed_resolve = None
+        self.warn_no_backreference = None
+        self.warn_default_parse_fail = None
+        self.highlight_lang = None
 
         # Populated once
         self.outdated_docs: set[str] = set()
@@ -103,6 +106,11 @@ class SphinxCodeAutoLink:
         self.inventory_map = app.config.codeautolink_inventory_map
         self.warn_missing_inventory = app.config.codeautolink_warn_on_missing_inventory
         self.warn_failed_resolve = app.config.codeautolink_warn_on_failed_resolve
+        self.warn_no_backreference = app.config.codeautolink_warn_on_no_backreference
+        self.warn_default_parse_fail = (
+            app.config.codeautolink_warn_on_default_parse_fail
+        )
+        self.highlight_lang = app.config.highlight_language
 
         # Append static resources path so references in setup() are valid
         app.config.html_static_path.append(
@@ -136,6 +144,8 @@ class SphinxCodeAutoLink:
             global_preface=self.global_preface,
             custom_blocks=self.custom_blocks,
             concat_default=self.concat_default,
+            default_highlight_lang=self.highlight_lang,
+            warn_default_parse_fail=self.warn_default_parse_fail,
         )
         doctree.walkabout(visitor)
         self.cache.transforms[visitor.current_document] = visitor.source_transforms
@@ -255,7 +265,11 @@ class SphinxCodeAutoLink:
             rm_vis = RemoveExtensionVisitor(doctree)
             return doctree.walkabout(rm_vis)
 
-        visitor = CodeRefsVisitor(doctree, code_refs=self.code_refs)
+        visitor = CodeRefsVisitor(
+            doctree,
+            code_refs=self.code_refs,
+            warn_no_backreference=self.warn_no_backreference,
+        )
         doctree.walk(visitor)
         return None
 

{sphinx_codeautolink-0.16.2 → sphinx_codeautolink-0.17.1}/src/sphinx_codeautolink/extension/backref.py

@@ -4,7 +4,10 @@ from dataclasses import dataclass
 
 from docutils import nodes
 
+from sphinx_codeautolink.warn import logger, warn_type
+
 from .directive import DeferredExamples
+from .translation import tr
 
 
 @dataclass
@@ -56,10 +59,15 @@ class CodeRefsVisitor(nodes.SparseNodeVisitor):
     """Replace :class:`DeferredCodeReferences` with table of concrete references."""
 
     def __init__(
-        self, *args, code_refs: dict[str, list[CodeExample]], **kwargs
+        self,
+        *args,
+        code_refs: dict[str, list[CodeExample]],
+        warn_no_backreference: bool = False,
+        **kwargs,
     ) -> None:
         super().__init__(*args, **kwargs)
         self.code_refs = code_refs
+        self.warn_no_backreference = warn_no_backreference
 
     def unknown_departure(self, node) -> None:
         """Ignore unknown nodes."""
@@ -79,6 +87,11 @@ class CodeRefsVisitor(nodes.SparseNodeVisitor):
         items = sorted(set(items))
 
         if not items:
+            if self.warn_no_backreference:
+                msg = f"No backreference for: '{node.ref}'"
+                logger.warning(
+                    msg, type=warn_type, subtype="no_backreference", location=node
+                )
             # Remove surrounding paragraph too
             node.parent.parent.remove(node.parent)
             return
@@ -100,7 +113,7 @@ class CodeRefsVisitor(nodes.SparseNodeVisitor):
             entry = nodes.entry()
             row += entry
             title = nodes.paragraph()
-            title += nodes.Text("References to ")
+            title += nodes.Text(tr("References to") + " ")
             title += orig_ref
             entry += title
 
@@ -120,7 +133,7 @@ class CodeRefsVisitor(nodes.SparseNodeVisitor):
         if node.collapse:
             details = DetailsNode()
             summary = SummaryNode()
-            summary += nodes.Text("Expand for references to ")
+            summary += nodes.Text(tr("Expand for references to") + " ")
             summary += orig_ref
             details += summary
             details += table