More consistent Sphinx themes

user_2051959 0
Viewed 451

Consider the following function

# in mymodule.py:

def myfunc(num,mystring):
    """
    replicates a string

    :param num: a positive integer
    :param mystring: a string
    :return: string concatenated with itself num times

    :Example:
        >>> num = 3
        >>> mystring = "lol"
        >>> myfunc(num, mystring)
        "lollollol"
    """
    return num*mystring

If I use Sphinx to generate code from my docstring, it looks like this (I'm using the default theme haiku this time, without many changes in the rst or conf.py file):

enter image description here

Are there any themes -or any other workarounds- that resolve the problems that I indicated with colors?

I tried different ones, and none worked, but I couldn't get any of the points 1.-4. to work.

EDIT The idea is that I don't want to edit the HTML, which is way to cumbersome. I want to make changes only to conf.py and index.rst files in my Sphinx docs directory in order to make the mentioned changes.

docstring python-sphinx themes python
1 Answers

CSS customization alone cannot solve this. Even though you can use ::before and after ::after selectors, I think JavaScript is better suited to deal with this.

You can add a custom Javascript file using the html_js_files option in conf.py. Your requirements 1, 2, and 3 should be possible using this.

#  ...

html_js_files = ['custom.js']

# ...

If you are using the code above in conf.py then your custom.js file should be located as follows

docs/
  _static/
    custom.css
    custom.js
  _templates/
  index.rst
  api.rst
  ...

An Example

Before adding custom.js

enter image description here

My custom.js file

window.onload = function () {
    // Change 'Parameters' to 'Arguments' 
    first_dt_elements = document.querySelectorAll('dl.field-list > dt:first-child');
    for(let i = 0; i< first_dt_elements.length; i++){
        first_dt_elements[i].innerText="Arguments";
    }
    // arguments same font and typeface etc..
    dl_methods = document.querySelectorAll('dl.function, dl.method');
    parameter_texts = []
    for(let i = 0; i< dl_methods.length; i++){
        params = [];
        param_elems=dl_methods[i].querySelectorAll('.sig-param');
        for (let j = 0; j< param_elems.length; j++){
            params.push(param_elems[j].innerText);
        }
        for( let k=0; k<params.length; k++){
            str = dl_methods[i].innerHTML;
            dl_methods[i].innerHTML= str.replace(
                RegExp(params[k], "g"), 
                '<span style="color:red;font-family:monospace;font-style:normal;">'
                + params[k] +
                '</span>'
            );
        }
    }
}

After building the html again

enter image description here

Regarding the optional requirement 4

Sphinx uses pygments for synatx highlighting. If you are not satisfied with this, you can use Highlightjs, Prismjs, Google code prettify etc.. by downloading and including them through html_js_files. But these are also syntax highlighters. Semantic highlighters that highlight variables are available for python, but I have not heard of anything that can be used with Sphinx.

Note:

  • I am using Alabaster theme. But this idea should work on most themes. However, you will have to write the custom.js file according to your theme.
  • My custom.js file is very simplistic and does not take into account all possibilities.
user_108255560
Related