Better link style for documentation index

Author: felix-hilden

docs/src/conf.py

@@ -56,6 +56,7 @@
 plot_html_show_formats = False
 plot_html_show_source_link = False
 
+html_static_path = ['static']
 
 def setup(app) -> None:
     app.add_object_type(
@@ -64,3 +65,8 @@ def setup(app) -> None:
         objname="configuration value",
         indextemplate="pair: %s; configuration value",
     )
+    app.connect('html-page-context', html_page_context_handler)
+
+def html_page_context_handler(app, pagename, templatename, context, doctree):
+    if pagename == 'index':
+        app.add_css_file('custom.css')

docs/src/index.rst

@@ -1,3 +1,5 @@
+.. _index:
+
 sphinx-codeautolink
 ===================
 |license|
@@ -16,6 +18,9 @@ Click any names in the example below for a demonstration:
        print(knight.taunt())
        knight.scratch()
 
+The link styles in this document have been modified to be obvious.
+The rest of this documentation uses the more subtle default style.
+
 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:

docs/src/reference.rst

@@ -141,6 +141,19 @@ Directives
 CSS class
 ---------
 The CSS class used in all code block links is ``sphinx-codeautolink-a``.
+An example of more obvious links is on the :ref:`landing page <index>`.
+The styles can be configured for all pages by defining ``html_static_path``
+and ``html_css_files`` to include in the documentation.
+To include only in specific documents, see the ``html-page-context`` event
+and the :meth:`Sphinx.add_css_file` function.
+
+.. code:: css
+
+   .sphinx-codeautolink-a{
+       border-bottom-color: #aaa;
+       border-bottom-style: dotted;
+       border-bottom-width: 2px;
+   }
 
 Cleanup functions
 -----------------

docs/src/static/custom.css

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