Sphinx **kwargs


I noticed that bokeh.plotting.figure.Figure.graph() documents its **kwargs parameters in the docstring, which is then built into the API reference docs by sphinx.

When I try to do this on my own project, sphinx complains:

WARNING: Inline literal start-string without end-string.

because reST specifies that asterisks in that form specify emphasis. Of course, a solution would be to escape the asterisks but then the docstring becomes less readable. How does bokeh.plotting.figure.Figure.graph() get away with it?

Thanks :slight_smile:

Hi @ZryletTC Do you mean the literal string **kwargs in this line of the reference guide ?

graph ( node_source, edge_source, layout_provider, **kwargs ) [source]

AFAIK that’s just coming from standard autodoc usage e.g.

.. autoclass:: bokeh.plotting.figure.Figure

is what we have in plotting.rst.

We do have specialized extensions for lots of various different things, e.g. our typed properties but we don’t do anything special with overriding function or method signatures.

Hi @Bryan,

Yes about **kwargs but I am referring to this line, not the signature:

**kwargs – Line Properties and Fill Properties

or as in the docstring:

**kwargs: :ref:`userguide_styling_line_properties` and :ref:`userguide_styling_fill_properties`

@ZryletTC the only thing I can think of is that we use Sphinx Napoleon configured for Google-style docstrings to process docstrings.

Huh, ok maybe it’s something about that, I’m using Napoleon with Numpy-style.

Also, maybe I’m just crazy because I don’t seem to be getting the error anymore :man_shrugging:

Thanks for taking a look at it.

1 Like