sphinx-codeautolink
===================
|license|

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 undelined name in the example below for a demonstration:

.. code:: python

   import lib

   knight = lib.Knight()
   while knight.limbs >= 0:
       print(knight.taunt())
       knight.scratch()

A directive to create a table of references from code examples to a single
definition is also provided, which can also be integrated with autodoc entries.
For example, :code:`.. autolink-examples:: lib.Knight` produces:

.. autolink-examples:: lib.Knight

Integration with intersphinx is seamless:

.. code:: python

   import numpy as np
   from matplotlib import pyplot as plt

   x = np.linspace(0, 2 * np.pi, 100)
   plt.plot(x, np.sin(x))
   plt.show()

Quick start
-----------
|pypi| |conda-forge|

sphinx-codeautolink can be installed from the following sources:

.. code:: sh

    $ pip install sphinx-codeautolink
    $ conda install -c conda-forge 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.

.. code:: python

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

That's it! Now your code examples are linked.
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:

- Package on `PyPI <https://pypi.org/project/sphinx-codeautolink>`_
- Development on `GitHub <https://github.com/felix-hilden/sphinx-codeautolink>`_

Caveats
-------
For a more thorough explanation, see :ref:`about`.

- Only works with HTML or DIRHTML documentation
- Only processes blocks, not inline code
- Doesn't run example code
- Parsing and type hint resolving is incomplete

Thanks
------
The inspiration for sphinx-codeautolink came from seeing similar awesome docs
generated by `Sphinx-Gallery <https://sphinx-gallery.github.io>`_!
Their source was also immensely helpful to read
when I was stumbling through Sphinx and docutils.
If you have a folder full of example Python scripts you'd like to include in
your documentation, you'll not be disappointed in their offer.

.. toctree::
   :hidden:
   :caption: Package

   release_notes
   reference
   about

.. toctree::
   :hidden:
   :caption: Guide

   examples
   example_library

.. toctree::
   :hidden:
   :caption: Links

   ↪ PyPI <https://pypi.org/project/sphinx-codeautolink>
   ↪ GitHub <https://github.com/felix-hilden/sphinx-codeautolink>

.. |pypi| image:: https://img.shields.io/pypi/v/sphinx-codeautolink.svg
   :target: https://pypi.org/project/sphinx-codeautolink
   :alt: PyPI package

.. |conda-forge| image:: https://anaconda.org/conda-forge/sphinx-codeautolink/badges/version.svg
    :target: https://anaconda.org/conda-forge/sphinx-codeautolink
    :alt: Conda-Forge package

.. |license| image:: https://img.shields.io/badge/License-MIT-blue.svg
   :target: https://choosealicense.com/licenses/mit
   :alt: License: MIT