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.

Sign up for GitHub

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

Jump to bottom

Multi-line args descriptions are not indented correctly #76

Open
jethrokuan opened this issue Jan 12, 2019 · 1 comment
Open

Multi-line args descriptions are not indented correctly #76

jethrokuan opened this issue Jan 12, 2019 · 1 comment

Comments

@jethrokuan
Copy link

Here's an example that illustrates the issue.

def foo(baz=1):
    """

    Args:
      baz: long-description breaking into multiple
        lines (Default value = 1)

    Returns:

    """
    pass

Formatting under google style results in:

def foo(baz=1):
    """

    Args:
      baz: long-description breaking into multiple
    lines (Default value = 1)

    Returns:

    """
    pass

where the second line of the arg description is indented incorrectly.
@introt
Copy link

introt commented Jun 12, 2021 •
edited
Loading

Same problem with rst, the subsequent lines have the same indentation as the field while they should be indented: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists

Edit: 0.4.0dev indents the lines correctly under rst style

@introt introt mentioned this issue Jun 12, 2021
Open
inmzhang added a commit to tqec/tqec that referenced this issue Feb 7, 2024
@inmzhang
Change the docstring style to Google style (#120)
154f6bd 
Closes #118 

This PR changes the docstring style of all the functions and classes
from rest to google style.

Initially, I used [pyment](https://github.com/dadadel/pyment) for this,
however, it turns out `pyment` cannot handle the multi-line argument
descriptions correctly[^1]. Then I turn to a less well-known package
[docconvert](https://github.com/cbillingham/docconvert) and it worked
out quite well.

I have checked the auto-converted files with `diff` preview in my IDE,
but slight errors might still exist. The conversion process can be
reproduced following the procedure below:

1. Install the `docconvert` python package: 
  ```shell
  pip install docconvert
  ```
2. Create the configuration file `docconvert.json` under the directory
of your `tqec` project:
  ```json
  {
      "input_style": "rest",
      "output_style": "google",
      "accepted_shebangs": [
          "python"
      ],
      "output": {
          "first_line": true,
          "replace_quotes": "\"\"\"",
          "standard_indent": "    ",
          "tab_length": 4,
          "realign": true,
          "max_line_length": 80,
          "use_optional": false,
          "remove_type_back_ticks": "true",
          "use_types": false,
          "separate_keywords": false
      }
  }
  ```
3. Run `docconvert` from the command line:
  ```shell
  docconvert --threads 4 --in-place --config docconvert.json src/tqec
  ```

[^1]: dadadel/pyment#76
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@jethrokuan @introt