Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docstring not correctly indented for Sphinx autodoc #300

Open
lochhh opened this issue Dec 19, 2023 · 0 comments
Open

Docstring not correctly indented for Sphinx autodoc #300

lochhh opened this issue Dec 19, 2023 · 0 comments
Labels
documentation Improvements or additions to documentation

Comments

@lochhh
Copy link
Contributor

lochhh commented Dec 19, 2023

When building aeon_docs, Sphinx autodoc gives the following warnings:

aeon_mecha/aeon/analysis/movies.py:docstring of aeon.analysis.movies.collatemovie:4: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/analysis/movies.py:docstring of aeon.analysis.movies.gridframes:8: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/analysis/movies.py:docstring of aeon.analysis.movies.gridmovie:5: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/analysis/movies.py:docstring of aeon.analysis.movies.triggerclip:4: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/analysis/plotting.py:docstring of aeon.analysis.plotting.colorline:5: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/analysis/plotting.py:docstring of aeon.analysis.plotting.rateplot:12: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/analysis/utils.py:docstring of aeon.analysis.utils.rate:12: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/io/api.py:docstring of aeon.io.api.load:11: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/io/reader.py:docstring of aeon.io.reader.Position:9: WARNING: Block quote ends without a blank line; unexpected unindent.
aeon_mecha/aeon/io/reader.py:docstring of aeon.io.reader.Position:11: WARNING: Definition list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/io/reader.py:docstring of aeon.io.reader.Subject:7: WARNING: Block quote ends without a blank line; unexpected unindent.
aeon_mecha/aeon/io/video.py:docstring of aeon.io.video.export:8: WARNING: Field list ends without a blank line; unexpected unindent.
aeon_mecha/aeon/io/video.py:docstring of aeon.io.video.frames:4: WARNING: Field list ends without a blank line; unexpected unindent.

and errors:

aeon_mecha/aeon/io/reader.py:docstring of aeon.io.reader.Log:7: ERROR: Unexpected indentation.
aeon_mecha/aeon/io/reader.py:docstring of aeon.io.reader.Position:8: ERROR: Unexpected indentation.
aeon_mecha/aeon/io/reader.py:docstring of aeon.io.reader.Subject:6: ERROR: Unexpected indentation.

The warnings are due to the args description spanning multiple lines and can be fixed by indenting these lines.
Similarly, the errors are due to the description of the items in the columns attribute spanning multiple lines. But in general, instead of e.g.

class Subject(Csv):
    """Extracts metadata for subjects entering and exiting the environment.

    Columns:
        id (str): Unique identifier of a subject in the environment.
        weight (float): Weight measurement of the subject on entering
            or exiting the environment.
        event (str): Event type. Can be one of `Enter`, `Exit` or `Remain`.
    """

columns should be placed under Attributes:

class Subject(Csv):
    """Extracts metadata for subjects entering and exiting the environment.

    Attributes:
        columns (list): List of column names expected in the CSV files. Includes:
            id (str): Unique identifier of a subject in the environment.
            weight (float): Weight measurement of the subject on entering or
            exiting the environment.
            event (str): Event type. Can be one of `Enter`, `Exit` or `Remain`.

    Args:
        pattern (str): A string pattern that matches the CSV files to be read.
    """
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

1 participant