handsdown-fork/handsdown/utils/docstring_formatter.py at main · FHPythonUtils/handsdown-fork · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
"""Translator of docstrings to Markdown format."""
from handsdown.utils.indent_trimmer import IndentTrimmer

__all__ = ["DocstringFormatter"]


class DocstringFormatter:
    """
    Translator of docstrings to Markdown format.

    Arguments:
        docstring -- Raw docstring.

    """

    def __init__(self, docstring: str) -> None:
        docstring = self._cleanup(docstring)
        docstring = IndentTrimmer.trim_empty_lines(docstring)
        docstring = IndentTrimmer.trim_text(docstring)
        lines = docstring.split("\n")
        self._lines = IndentTrimmer.trim_lines(lines)

    @staticmethod
    def _cleanup(docstring: str) -> str:
        """
        Fix multiline docstrings starting with no newline after quotes.

        Arguments:
            docstring -- Raw docstring.

        Returns:
            Aligned docstring.

        """
        if "\n" in docstring and docstring[0] != "\n":
            lines = docstring.split("\n")
            next_line_index = 1
            next_line = lines[next_line_index]
            while not next_line.strip() and next_line_index < len(lines) - 1:
                next_line_index += 1
                next_line = lines[next_line_index]

            indent = IndentTrimmer.get_line_indent(next_line)
            line_indent = " " * indent
            docstring = f"\n{line_indent}{docstring}"

        return IndentTrimmer.trim_text(docstring)

    def _parse_flask_title(self) -> None:
        lines = list(self._lines)
        for index, line in enumerate(lines):
            if line.startswith("~~~~"):
                if index:
                    self._lines[index - 1] = f"# {self._lines[index - 1]}"
                self._lines.pop(index)

    def render(self) -> str:
        """
        Get Markdown-friendly docstring.

        Returns:
            A cleaned up docstring.

        """
        self._parse_flask_title()
        return "\n".join(self._lines)