Better default link style & highlighted examples

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

docs/src/conf.py

@@ -56,6 +56,9 @@
 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(

docs/src/examples.rst

@@ -300,24 +300,29 @@ 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
 
    # conf.py
    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 dotted lines 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-color: #aaa;
        border-bottom-style: dotted;
        border-bottom-width: 1px;
    }

docs/src/index.rst

@@ -56,8 +56,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:

docs/src/reference.rst

@@ -141,6 +141,9 @@ Directives
 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
 -----------------

docs/src/static/custom.css

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

src/sphinx_codeautolink/__init__.py

@@ -1,5 +1,8 @@
 """Sphinx extension for linking code examples to reference documentation."""
 
+from importlib.resources import files
+from shutil import copyfile
+
 from sphinx.application import Sphinx
 
 from .extension import SphinxCodeAutoLink, backref, directive

src/sphinx_codeautolink/static/sphinx-codeautolink.css

@@ -1,16 +1,13 @@
-.sphinx-codeautolink-a:link{
+.sphinx-codeautolink-a{
     color: inherit;
     text-decoration: none;
 }
-.sphinx-codeautolink-a:active{
+.sphinx-codeautolink-a:link{
     color: inherit;
-    text-decoration: none;
 }
 .sphinx-codeautolink-a:visited{
     color: inherit;
-    text-decoration: none;
 }
 .sphinx-codeautolink-a:hover{
     color: rgb(0, 139, 139);
-    text-decoration: none;
 }