directive appearing as literal text in rendered document

Question

I want to display the docstrings for two functions, in between a couple of section headers, as follows:

===
API
===

.. autofunction:: parsons.aws.distribute_task

.. autofunction:: parsons.aws.event_command

***
S3
***

Both of the docstrings are appearing in the rendered HTML, but the second function also shows the Sphinx directive .. autofunction:: parsons.aws.event_command as text below the docstring:

Any ideas as to why is this occurring and how can I get rid of it?

You can see the problem (and all the code for this project) at the top of this file on GitHub:

https://github.com/move-coop/parsons/blob/master/docs/aws.rst

And in the built version of the documentation:

https://move-coop.github.io/parsons/html/aws.html

Answer 1

The code on GitHub doesn't have a blank line separating the two .. autofunction:: directives:

.. autofunction :: parsons.aws.distribute_task
.. autofunction :: parsons.aws.event_command

reStructuredText rules for directives states that:

Actions taken in response to directives and the interpretation of text in the directive content block or *subsequent text block(s) are directive-dependent.

So looking at the "Syntax diagram", and the "three logical parts" of a directive block:

There are three logical parts to the directive block:

    Directive arguments.
    Directive options.
    Directive content.

(...)

Syntax diagram:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

To me it's not entirely clear if "subsequent text block(s)" (that will have a directive dependent behavior) applies to a directive immediately following another or only to the "three logical parts of the directive block".

A directive counts as an Explicit Markup Block so the third rule implies a directive should end before an unindented line.

An explicit markup block is a text block: (...)

• which ends before an unindented line.

Notice there's no clear ending between the two .. autofunction:: directives (both are unindented). Further on it is stated:

Blank lines are required between explicit markup blocks and other elements, but are optional between explicit markup blocks where unambiguous.

It is generally safer to have blank lines after directives, to prevent any unspecified behavior (in your case, having the directive render normally and also be included textually).

If you leave a blank line after the directives it should work as expected.

EDIT: There's this old style guide mentioning 2 blank lines should be placed before overlined sections. I can't explain why (maybe it's a GitHub or readthedocs local issue) but apparently it solved the problem.