4

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:
bdemchak
  • 263
  • 2
  • 10
  • 1
    Sphinx is a documentation system that divides sementic and format as good as possible (as it should be). In general it is not a good idea to add format by content. If you want to change the formatting adapt the templates and/or stylesheets. – Klaus D. Feb 13 '20 at 02:21
  • 1
    With `autofunction` instead of `automodule`, it is possible to achieve what you want. Similar to https://stackoverflow.com/a/19280972/407651 – mzjn Feb 13 '20 at 08:06

1 Answers1

8

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.

bdemchak
  • 263
  • 2
  • 10
  • Here's another excellent [reference](http://stackoverflow.com/questions/32079200/how-do-i-set-up-custom-styles-for-restructuredtext-sphinx-readthedocs-etc/32079202#32079202) for how to do things like this – bdemchak Feb 14 '20 at 18:21
  • Worked like a charm, thanks! In my case, the folders `_templates` and `_static` already existed, but within the `source` folder inside the `docs` folder. I added the `css` subfolder to `_static` and the files you suggested to them and everything worked perfectly. – Laurin Herbsthofer May 18 '21 at 11:55