Better default link style & highlighted examples (#171)

Author: felix-hilden

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,25 +300,30 @@ 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 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{

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:

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: #ccc;
+    border-bottom-style: solid;
+    border-bottom-width: 1px;
+}

readme.rst

@@ -24,7 +24,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``.
@@ -38,9 +37,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>`_.
 
 .. |pypi| image:: https://img.shields.io/pypi/v/sphinx-codeautolink.svg
    :target: https://pypi.org/project/sphinx-codeautolink

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

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;
 }