8000 Adding a ReST block immediately after the module docstring breaks the generated .rst file · Issue #473 · sphinx-gallery/sphinx-gallery · GitHub
[go: up one dir, main page]

Skip to content

Adding a ReST block immediately after the module docstring breaks the generated .rst file #473

@timhoffm

Description

@timhoffm

Bug

It appears that both module docstring and ReST blocks are stripped of blank lines at the beginning and end.

Thus the example from https://sphinx-gallery.github.io/syntax.html

"""
This is my example script
=========================

This example doesn't do much, it just makes a simple plot
"""

###############################################################################
# This is a section header
# ------------------------

would result in an .rst file with

This example doesn't do much, it just makes a simple plot
This is a section header
------------------------

resulting in incorrect rendering of the section due to a missing line before it. A similar effect happens if you have just plain text paragraphs: They will be joined.

This appears to be a common pitfall:
matplotlib/matplotlib#13911
matplotlib/matplotlib#13950

Proposed fix

Probably the correct fix would be to always add a blank line after the module docstring text in the generated .rst file.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      0