Bullet list style for single parameter functions in RTD theme using autodoc and Sphinx?

Question

I've noticed that when I use autodoc with the ReadTheDoc theme, if I have multiple arguments in my functions they are listed in a bullet list style:

• arg1
• arg2
• ...

but if there is only 1 argument then it is not using the bullet list style which is a bit silly to me since it breaks the continuity of the design.

I've found how to remove the disc via CSS to make things more uniform but I actually want to do the opposite and have the disk for the single argument functions. At this point, I'm not sure it is a CSS change and I do not know how to do that.

I've also noticed the same thing in different docs.

Here is the rendered html:

Here are the 2 methods:

def add_attribute(self, name, index):
    """
    :param name: The name attached to the attribute.
    :param index: The position of the attribute within the list of attributes. """
    print("")

def delete_attribute(self, name):
    """
    :param name: The name of the attribute to delete."""
    print("")

Here is the my .rst:

API
----------------

.. automodule:: my_module
   :members:

Here is the conf.py

extensions = [
    'sphinx_rtd_theme',
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.coverage',
    'sphinx.ext.autosummary',
]

templates_path = ['_templates']

language = 'python'

exclude_patterns = []

html_theme = "sphinx_rtd_theme"

html_static_path = ['_static']

autosummary_generate = True

Any idea? Cheers!

Answer 1

After a lot of digging, I've found a partial workaround for this.

My solution involves manually editing the produced HTML files to insert the missing bullet points.

Required conf.py changes:

# Register hook to run when build is complete
def setup(app):
    app.connect('build-finished', on_build_finished)


# Hook implementation
def on_build_finished(app, exception):
    add_single_param_bullets("_build/html/index.html")


# Function to actually add the bullet points by overwriting the given HTML file
def add_single_param_bullets(file_path):
    print('Add single parameter bullets in {:s}'.format(file_path))
    if not os.path.exists(file_path):
        print('  File not found, skipping...')
        return
    lines_enc = []
    with open(file_path, 'rb') as f:
        for l in f.readlines():
            # Check for html that indicates single parameter function
            if b'<dd class="field-odd"><p><strong>' in l:
                # Work out the encoding if not defined
                enc = None
                if enc is None:
                    import chardet
                    enc = chardet.detect(l)['encoding']
                # Decode html and get the parameter information that needs adding
                l_dec = l.decode(enc)
                l_insert = l_dec.replace('<dd class="field-odd">', '').replace('\r\n', '')
                # Add new encoded lines to output
                lines_enc.append('<dd class="field-odd"><ul class="simple">'.encode('utf=8'))
                lines_enc.append('<li>{:s}</li>'.format(l_insert).encode(enc))
                lines_enc.append('</ul>'.encode('utf=8'))
            else:
                lines_enc.append(l)
    # Overwrite the original file with the new changes
    with open(file_path, 'wb') as f:
        for l in lines_enc:
            f.write(l)

In my case, I only have single argument functions in index.html. However, you can register additional files in on_build_finished.

A few things to note:

• This only edits the produced HTML files, and doesn't actually solve the underlying problem. I dug through the source for a bit but couldn't find why the bullet points aren't added for single parameter function.
• The problem is not just for the RTD theme. It seems to occur with the basic theme as well. So I suspect it's a deeper problem with Sphinx rather than the RTD theme.
• The code above somewhat deals with different encodings in the original HTML.
• This does not work on the RTD website. As the HTML files are edited in place, and the RTD build outputs the HTML files to a different directory, this solution doesn't seem to work on the RTD website. This is quite annoying. A solution would be to somehow change the RTD build process, or tell RTD to use pre-built HTML sources rather than building its own, but I don't know how to do so.
• After spending a few hours working all this out, I actually think it looks better without the bullet points...