Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to create a horizontal line and white space between function signatures in Sphinx autodoc

I have found sphinx options for most of what I want to do, but I can't see how to inject white space and a horizontal line between function signatures when using autodoc.

Here's what autodoc produces:

get_all_edges(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_edges

get_all_nodes(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_nodes

get_edge_count(network=None, base_url='http://localhost:1234/v1')
   docstring for get_edge_count

Here's what I'm trying to get:

get_all_edges(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_edges

   ------------------------------------------------------------

get_all_nodes(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_nodes

   ------------------------------------------------------------

get_edge_count(network=None, base_url='http://localhost:1234/v1')
   docstring for get_edge_count

... or something close to this. I'm not passionate about whether the last function signature has a trailing separator. Maybe this is simple, but I'm not seeing it. Thanks!

FYI, here are the autodoc directives that produced my function signatures:

PyCy3.networks module
---------------------

.. automodule:: PyCy3.networks
    :members:
    :undoc-members:
    :show-inheritance:
like image 851
bdemchak Avatar asked Mar 02 '23 19:03

bdemchak


1 Answers

As it turns out, this wasn't so hard ... after doing a day of research. :)

The key insights were:

  1. autodoc creates HTML so that each function has class="function"
  2. class "function" isn't defined anywhere ... it's a hook for just this purpose
  3. it's possible to define "function" using a combination of _template and _static folders in my doc folder

The inspiration for #3 was here: Modifying content width of the Sphinx theme 'Read the Docs'

(I am using readthedocs, so I'm not completely sure this will work with command line sphinx.)

In my case, the "docs" folder has all of my sphinx files. I created new sub-folders: "_templates" and "_static/css".

In _templates, I created a new file "layout.html":

{% extends "!layout.html" %}
{% set css_files = css_files + [ "_static/css/functions.css" ] %}

In _static/css, I created a new file "functions.css":

.function {
    border-bottom: 3px solid #d0d0d0;
    padding-bottom: 10px;
    padding-top: 10px;
}

So, layout.html extends the default layout.html and injects my new css.

I think autodoc creates other hooks for this purpose (e.g., sig-name, sig-paren and sig-param) for the various elements of a function signature. You can discover this for yourself by using Chrome's page source inspector in the web page debugger.

like image 116
bdemchak Avatar answered Mar 05 '23 09:03

bdemchak