A literal "*" in RestructuredText

Question

I am looking at this snippet of code:

def ook(*args):
    """Some silly function.

    :param *args: Optional arguments.
    """
    ...

And as soon as I run Sphinx, I get the oh-so helpful error:

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

So, I tried param ``*``args, param :literal:'*' args and still get the warning.

How do I have a literal '*' in restructuredText?

In this case, I would not include the asterisk in the param definition - it's not part of the parameter name — Ninjakannon, Dec 09 '19 at 14:09

knitti · Accepted Answer · 2015-05-26T09:50:12.583

29

You could use the (somewhat ugly) backslash quotation: \*

EDIT: As an (somewhat ugly) addendum, if you are concerned about pylint warning about the backslash, you could add a r to the string literal: r""" ... docstring ... """. This was descibed in this pylint issue.

Having different text processing systems play nicely together destroys sometimes the aesthetics.

edited May 26 '15 at 09:50

answered May 26 '15 at 09:39

knitti

6,817
31
42

2

Just wanted to add that this also happens with quotes, as in `""" a "comment """`, and can also be fixed with a backslash, like `""" a \"comment\" """"`. – jxmorris12 Jul 01 '20 at 16:17

score 1 · Answer 2 · answered Jul 08 '15 at 23:07

1

In restructuredtext you can use the .. code:: python directive.

http://docutils.sourceforge.net/docs/ref/rst/directives.html#code

This allows you to create a literal block of python code without any ugly '\' characters.

It looks like this:

.. code:: python

    def ook(*args):
        """Some silly function.

        :param *args: Optional arguments.
        """
        ...

An example using your function is here:

http://rst.ninjs.org/?n=c8ad07eaea190745755a6d80d37786e6&theme=basic

answered Jul 08 '15 at 23:07

matthewrsj

81
1
8

2

This is for in-code documentation, so I want the "*" character in the doc string, not show the whole function/method. – Sardathrion - against SE abuse Jul 09 '15 at 06:32
the link is dead – baxx Feb 07 '20 at 15:37
in 2023 this is the only solution that worked for me. the accepted solution did not – Sigmatics Aug 24 '23 at 15:34

Y4nhu1 · Answer 3 · 2023-04-17T11:37:51.847

1

:param `*args`:

In addition to \*, the above works for me :)

edited Apr 17 '23 at 11:37

answered Apr 17 '23 at 02:19

Y4nhu1

116
11

A literal "*" in RestructuredText

3 Answers3