From 9475e522aaba6466d4741ad57953a75bb183c4c4 Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Tue, 10 Oct 2023 15:35:21 +0200
Subject: [PATCH 01/19] Basic support for Google style docstrings

---
 docstring_to_markdown/__init__.py |   5 ++
 docstring_to_markdown/google.py   | 137 ++++++++++++++++++++++++++++++
 tests/test_google.py              |  36 ++++++++
 3 files changed, 178 insertions(+)
 create mode 100644 docstring_to_markdown/google.py
 create mode 100644 tests/test_google.py

diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index c81e124..520368f 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -1,3 +1,4 @@
+from .google import google_to_markdown, looks_like_google
 from .rst import looks_like_rst, rst_to_markdown
 
 __version__ = "0.12"
@@ -10,4 +11,8 @@ class UnknownFormatError(Exception):
 def convert(docstring: str) -> str:
     if looks_like_rst(docstring):
         return rst_to_markdown(docstring)
+
+    if looks_like_google(docstring):
+        return google_to_markdown(docstring)
+
     raise UnknownFormatError()
diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
new file mode 100644
index 0000000..e3aee7d
--- /dev/null
+++ b/docstring_to_markdown/google.py
@@ -0,0 +1,137 @@
+import re
+from typing import Dict, List, Union
+
+_GOOGLE_SECTIONS: List[str] = [
+    "Args",
+    "Returns",
+    "Raises",
+    "Yields",
+    "Example",
+    "Examples",
+    "Attributes",
+    "Note",
+]
+
+ESCAPE_RULES = {
+    # Avoid Markdown in magic methods or filenames like __init__.py
+    r"__(?P<text>\S+)__": r"\_\_\g<text>\_\_",
+}
+
+
+class Section:
+    def __init__(self, name: str, content: str) -> None:
+        self.name = name
+        self.content = ""
+
+        self._parse(content)
+
+    def _parse(self, content: str) -> None:
+        content = content.rstrip("\n")
+
+        parts = []
+        cur_part = []
+
+        for line in content.split("\n"):
+            line = line.replace("    ", "", 1)
+
+            if line.startswith(" "):
+                # Continuation from a multiline description
+                cur_part.append(line)
+                continue
+
+            if cur_part:
+                # Leaving multiline description
+                parts.append(cur_part)
+                cur_part = [line]
+            else:
+                # Entering new description part
+                cur_part.append(line)
+
+        # Last part
+        parts.append(cur_part)
+
+        # Format section
+        for part in parts:
+            self.content += "- {}\n".format(part[0])
+
+            for line in part[1:]:
+                self.content += "  {}\n".format(line)
+
+        self.content = self.content.rstrip("\n")
+
+    def as_markdown(self) -> str:
+        return "# {}\n\n{}\n\n".format(self.name, self.content)
+
+    def __repr__(self) -> str:
+        return "Section(name={}, content={})".format(self.name, self.content)
+
+
+class GoogleDocstring:
+    def __init__(self, docstring: str) -> None:
+        self.sections: list[Section] = []
+        self.description: str = ""
+
+        self._parse(docstring)
+
+    def _parse(self, docstring: str) -> None:
+        self.sections = []
+        self.description = ""
+
+        buf = ""
+        cur_section = ""
+
+        for line in docstring.split("\n"):
+            if is_section(line):
+                # Entering new section
+                if cur_section:
+                    # Leaving previous section, save it and reset buffer
+                    self.sections.append(Section(cur_section, buf))
+                    buf = ""
+
+                # Remember currently parsed section
+                cur_section = line.rstrip(":")
+                continue
+
+            # Parse section content
+            if cur_section:
+                buf += line + "\n"
+            else:
+                # Before setting cur_section, we're parsing the function description
+                self.description += line + "\n"
+
+        # Last section
+        self.sections.append(Section(cur_section, buf))
+
+    def as_markdown(self) -> str:
+        text = self.description
+
+        for section in self.sections:
+            text += section.as_markdown()
+
+        return text.rstrip("\n") + "\n"  # Only keep one last newline
+
+
+def is_section(line: str) -> bool:
+    for section in _GOOGLE_SECTIONS:
+        if re.search(r"{}:".format(section), line):
+            return True
+
+    return False
+
+
+def looks_like_google(value: str) -> bool:
+    for section in _GOOGLE_SECTIONS:
+        if re.search(r"{}:\n".format(section), value):
+            return True
+
+    return False
+
+
+def google_to_markdown(text: str, extract_signature: bool = True) -> str:
+    # Escape parts we don't want to render
+    for pattern, replacement in ESCAPE_RULES.items():
+        text = re.sub(pattern, replacement, text)
+
+    docstring = GoogleDocstring(text)
+
+    return docstring.as_markdown()
diff --git a/tests/test_google.py b/tests/test_google.py
new file mode 100644
index 0000000..521ecc7
--- /dev/null
+++ b/tests/test_google.py
@@ -0,0 +1,36 @@
+from docstring_to_markdown.google import google_to_markdown, looks_like_google
+
+BASIC_EXAMPLE = """Do **something**.
+
+Args:
+    a: some arg
+    b: some arg
+
+Returns:
+    Same *stuff*
+"""
+
+BASIC_EXAMPLE_MD = """Do **something**.
+
+# Args
+
+- a: some arg
+- b: some arg
+
+# Returns
+
+- Same *stuff*
+"""
+
+
+def test_looks_like_google_recognises_google():
+    assert looks_like_google(BASIC_EXAMPLE)
+
+
+def test_looks_like_google_ignores_plain_text():
+    assert not looks_like_google("This is plain text")
+    assert not looks_like_google("See Also\n--------\n")
+
+
+def test_google_to_markdown():
+    assert google_to_markdown(BASIC_EXAMPLE) == BASIC_EXAMPLE_MD

From 31c398506d7bb4465b923b75a32051e1217884c1 Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 09:01:18 +0200
Subject: [PATCH 02/19] Parse individual arguments

---
 docstring_to_markdown/google.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index e3aee7d..911eb3c 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -52,7 +52,15 @@ def _parse(self, content: str) -> None:
 
         # Format section
         for part in parts:
-            self.content += "- {}\n".format(part[0])
+            if ":" in part[0]:
+                spl = part[0].split(":")
+
+                arg = spl[0]
+                description = ":".join(spl[1:])
+
+                self.content += "- `{}`: {}\n".format(arg, description)
+            else:
+                self.content += "- {}\n".format(part[0])
 
             for line in part[1:]:
                 self.content += "  {}\n".format(line)
@@ -60,7 +68,7 @@ def _parse(self, content: str) -> None:
         self.content = self.content.rstrip("\n")
 
     def as_markdown(self) -> str:
-        return "# {}\n\n{}\n\n".format(self.name, self.content)
+        return "#### {}\n\n{}\n\n".format(self.name, self.content)
 
     def __repr__(self) -> str:
         return "Section(name={}, content={})".format(self.name, self.content)

From 4d8d55cefff9a95eb81d8d7ef7dbea6e72f9958f Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 10:25:39 +0200
Subject: [PATCH 03/19] Fix indentation of arguments

---
 docstring_to_markdown/google.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index 911eb3c..43844b9 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -1,4 +1,5 @@
 import re
+from textwrap import dedent
 from typing import Dict, List, Union
 
 _GOOGLE_SECTIONS: List[str] = [
@@ -10,6 +11,7 @@
     "Examples",
     "Attributes",
     "Note",
+    "Todo",
 ]
 
 ESCAPE_RULES = {
@@ -52,18 +54,21 @@ def _parse(self, content: str) -> None:
 
         # Format section
         for part in parts:
+            indentation = ""
+
             if ":" in part[0]:
                 spl = part[0].split(":")
 
                 arg = spl[0]
-                description = ":".join(spl[1:])
+                description = ":".join(spl[1:]).lstrip()
+                indentation = (len(arg) + 6) * " "
 
                 self.content += "- `{}`: {}\n".format(arg, description)
             else:
                 self.content += "- {}\n".format(part[0])
 
             for line in part[1:]:
-                self.content += "  {}\n".format(line)
+                self.content += "{}{}\n".format(indentation, line.lstrip())
 
         self.content = self.content.rstrip("\n")
 

From 683d1cce5e0a2ae13d1cfed240ae0cdcbb833c87 Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 10:28:07 +0200
Subject: [PATCH 04/19] Skip line parsing in some sections

---
 docstring_to_markdown/google.py | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index 43844b9..94994aa 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -2,7 +2,8 @@
 from textwrap import dedent
 from typing import Dict, List, Union
 
-_GOOGLE_SECTIONS: List[str] = [
+# All possible sections in Google style docstrings
+SECTION_HEADERS: List[str] = [
     "Args",
     "Returns",
     "Raises",
@@ -14,6 +15,14 @@
     "Todo",
 ]
 
+# These sections will not be parsed as a list of arguments/return values/etc
+PLAIN_TEXT_SECTIONS: List[str] = [
+    "Examples",
+    "Example",
+    "Note",
+    "Todo",
+]
+
 ESCAPE_RULES = {
     # Avoid Markdown in magic methods or filenames like __init__.py
     r"__(?P<text>\S+)__": r"\_\_\g<text>\_\_",
@@ -30,6 +39,10 @@ def __init__(self, name: str, content: str) -> None:
     def _parse(self, content: str) -> None:
         content = content.rstrip("\n")
 
+        if self.name in PLAIN_TEXT_SECTIONS:
+            self.content = dedent(content)
+            return
+
         parts = []
         cur_part = []
 
@@ -125,7 +138,7 @@ def as_markdown(self) -> str:
 
 
 def is_section(line: str) -> bool:
-    for section in _GOOGLE_SECTIONS:
+    for section in SECTION_HEADERS:
         if re.search(r"{}:".format(section), line):
             return True
 
@@ -133,7 +146,7 @@ def is_section(line: str) -> bool:
 
 
 def looks_like_google(value: str) -> bool:
-    for section in _GOOGLE_SECTIONS:
+    for section in SECTION_HEADERS:
         if re.search(r"{}:\n".format(section), value):
             return True
 

From 1cbb47358fa0ec30c2d4ff5ee9aeb7952eeafe86 Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 10:49:13 +0200
Subject: [PATCH 05/19] Remove repr

Only used it for debugging
---
 docstring_to_markdown/google.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index 94994aa..6536616 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -88,8 +88,6 @@ def _parse(self, content: str) -> None:
     def as_markdown(self) -> str:
         return "#### {}\n\n{}\n\n".format(self.name, self.content)
 
-    def __repr__(self) -> str:
-        return "Section(name={}, content={})".format(self.name, self.content)
 
 
 class GoogleDocstring:

From a2d9a88cff65be3bef5a9868396b3325944b0cf2 Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 10:56:16 +0200
Subject: [PATCH 06/19] Add tests

---
 tests/test_google.py | 110 +++++++++++++++++++++++++++++++++++++++----
 1 file changed, 102 insertions(+), 8 deletions(-)

diff --git a/tests/test_google.py b/tests/test_google.py
index 521ecc7..ab3c63d 100644
--- a/tests/test_google.py
+++ b/tests/test_google.py
@@ -1,7 +1,11 @@
+import pytest
+
 from docstring_to_markdown.google import google_to_markdown, looks_like_google
 
 BASIC_EXAMPLE = """Do **something**.
 
+Some more detailed description.
+
 Args:
     a: some arg
     b: some arg
@@ -12,19 +16,104 @@
 
 BASIC_EXAMPLE_MD = """Do **something**.
 
-# Args
+Some more detailed description.
+
+#### Args
 
-- a: some arg
-- b: some arg
+- `a`: some arg
+- `b`: some arg
 
-# Returns
+#### Returns
 
 - Same *stuff*
 """
 
+ESCAPE_MAGIC_METHOD = """Example.
+
+Args:
+    a: see __init__.py
+"""
+
+ESCAPE_MAGIC_METHOD_MD = """Example.
+
+#### Args
+
+- `a`: see \\_\\_init\\_\\_.py
+"""
+
+PLAIN_SECTION = """Example.
+
+Args:
+    a: some arg
+
+Note:
+    Do not use this.
+
+Example:
+    Do it like this.
+"""
+
+PLAIN_SECTION_MD = """Example.
+
+#### Args
+
+- `a`: some arg
+
+#### Note
+
+Do not use this.
+
+#### Example
+
+Do it like this.
+"""
+
+MULTILINE_ARG_DESCRIPTION = """Example.
+
+Args:
+    a (str): This is a long description
+             spanning over several lines
+        also with broken indentation
+    b (str): Second arg
+"""
+
+MULTILINE_ARG_DESCRIPTION_MD = """Example.
+
+#### Args
+
+- `a (str)`: This is a long description
+             spanning over several lines
+             also with broken indentation
+- `b (str)`: Second arg
+"""
+
+GOOGLE_CASES = {
+    "basic example": {
+        "google": BASIC_EXAMPLE,
+        "md": BASIC_EXAMPLE_MD,
+    },
+    "escape magic method": {
+        "google": ESCAPE_MAGIC_METHOD,
+        "md": ESCAPE_MAGIC_METHOD_MD,
+    },
+    "plain section": {
+        "google": PLAIN_SECTION,
+        "md": PLAIN_SECTION_MD,
+    },
+    "multiline arg description": {
+        "google": MULTILINE_ARG_DESCRIPTION,
+        "md": MULTILINE_ARG_DESCRIPTION_MD,
+    },
+}
+
 
-def test_looks_like_google_recognises_google():
-    assert looks_like_google(BASIC_EXAMPLE)
+@pytest.mark.parametrize(
+    "google",
+    [case["google"] for case in GOOGLE_CASES.values()],
+    ids=GOOGLE_CASES.keys(),
+)
+def test_looks_like_google_recognises_google(google):
+    assert looks_like_google(google)
 
 
 def test_looks_like_google_ignores_plain_text():
@@ -32,5 +121,10 @@ def test_looks_like_google_ignores_plain_text():
     assert not looks_like_google("See Also\n--------\n")
 
 
-def test_google_to_markdown():
-    assert google_to_markdown(BASIC_EXAMPLE) == BASIC_EXAMPLE_MD
+@pytest.mark.parametrize(
+    "google,markdown",
+    [[case["google"], case["md"]] for case in GOOGLE_CASES.values()],
+    ids=GOOGLE_CASES.keys(),
+)
+def test_google_to_markdown(google, markdown):
+    assert google_to_markdown(google) == markdown

From 2318f9aec23aeb7a6ab89ea9b2b831c6cdf6b89c Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 11:49:23 +0200
Subject: [PATCH 07/19] Support indented arg descriptions

---
 docstring_to_markdown/google.py | 18 ++++++++++++++----
 tests/test_google.py            |  5 +++++
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index 6536616..ad07226 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -1,6 +1,6 @@
 import re
 from textwrap import dedent
-from typing import Dict, List, Union
+from typing import List
 
 # All possible sections in Google style docstrings
 SECTION_HEADERS: List[str] = [
@@ -68,6 +68,7 @@ def _parse(self, content: str) -> None:
         # Format section
         for part in parts:
             indentation = ""
+            skip_first = False
 
             if ":" in part[0]:
                 spl = part[0].split(":")
@@ -76,11 +77,21 @@ def _parse(self, content: str) -> None:
                 description = ":".join(spl[1:]).lstrip()
                 indentation = (len(arg) + 6) * " "
 
-                self.content += "- `{}`: {}\n".format(arg, description)
+                if description:
+                    self.content += "- `{}`: {}\n".format(arg, description)
+                else:
+                    skip_first = True
+                    self.content += "- `{}`: ".format(arg)
             else:
                 self.content += "- {}\n".format(part[0])
 
-            for line in part[1:]:
+            for n, line in enumerate(part[1:]):
+                if skip_first and n == 0:
+                    # This ensures that indented args get moved to the
+                    # previous line
+                    self.content += "{}\n".format(line.lstrip())
+                    continue
+
                 self.content += "{}{}\n".format(indentation, line.lstrip())
 
         self.content = self.content.rstrip("\n")
@@ -89,7 +100,6 @@ def as_markdown(self) -> str:
         return "#### {}\n\n{}\n\n".format(self.name, self.content)
 
 
-
 class GoogleDocstring:
     def __init__(self, docstring: str) -> None:
         self.sections: list[Section] = []
diff --git a/tests/test_google.py b/tests/test_google.py
index ab3c63d..78486bc 100644
--- a/tests/test_google.py
+++ b/tests/test_google.py
@@ -75,6 +75,9 @@
              spanning over several lines
         also with broken indentation
     b (str): Second arg
+    c (str):
+        On the next line
+        And also multiple lines
 """
 
 MULTILINE_ARG_DESCRIPTION_MD = """Example.
@@ -85,6 +88,8 @@
              spanning over several lines
              also with broken indentation
 - `b (str)`: Second arg
+- `c (str)`: On the next line
+             And also multiple lines
 """
 
 GOOGLE_CASES = {

From 33129fc219a4c2c9b3a9537eb9c50d93c7cb1804 Mon Sep 17 00:00:00 2001
From: staticf0x <staticf0x@pm.me>
Date: Wed, 11 Oct 2023 13:35:29 +0200
Subject: [PATCH 08/19] Fix typing compatibility

---
 docstring_to_markdown/google.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index ad07226..e3ca5a8 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -102,7 +102,7 @@ def as_markdown(self) -> str:
 
 class GoogleDocstring:
     def __init__(self, docstring: str) -> None:
-        self.sections: list[Section] = []
+        self.sections: List[Section] = []
         self.description: str = ""
 
         self._parse(docstring)

From ea693e05a4dd9b3978f329e09e6e14037435e2a9 Mon Sep 17 00:00:00 2001
From: krassowski <5832902+krassowski@users.noreply.github.com>
Date: Wed, 11 Oct 2023 19:13:12 +0100
Subject: [PATCH 09/19] Prepare release v0.13

---
 docstring_to_markdown/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index 520368f..b4d0bdf 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -1,7 +1,7 @@
 from .google import google_to_markdown, looks_like_google
 from .rst import looks_like_rst, rst_to_markdown
 
-__version__ = "0.12"
+__version__ = "0.13"
 
 
 class UnknownFormatError(Exception):

From cab53d55d8d1dfe5cdb5314a9658508970413efd Mon Sep 17 00:00:00 2001
From: krassowski <5832902+krassowski@users.noreply.github.com>
Date: Wed, 11 Oct 2023 19:15:51 +0100
Subject: [PATCH 10/19] Update README with Google docstring note

---
 README.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 2f09ef6..6cea177 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,8 @@
 On the fly conversion of Python docstrings to markdown
 
 - Python 3.6+
-- currently can recognise reStructuredText and convert multiple of its features to Markdown
-- in the future will be able to convert Google docstrings too
+- can recognise reStructuredText and convert multiple of its features to Markdown
+- since v0.13 includes initial support for Google-formatted docstrings
 
 ### Installation
 
@@ -16,7 +16,6 @@ On the fly conversion of Python docstrings to markdown
 pip install docstring-to-markdown
 ```
 
-
 ### Example
 
 Convert reStructuredText:

From dbc549477d1eda6ef4cd0058d2de8dbf507a1536 Mon Sep 17 00:00:00 2001
From: krassowski <5832902+krassowski@users.noreply.github.com>
Date: Mon, 19 Feb 2024 15:22:34 +0000
Subject: [PATCH 11/19] Add plain text and cPython docs support

---
 docstring_to_markdown/__init__.py |   9 +++
 docstring_to_markdown/_utils.py   |   5 ++
 docstring_to_markdown/cpython.py  |  37 +++++++++++
 docstring_to_markdown/plain.py    |  27 ++++++++
 setup.cfg                         |   2 +-
 tests/test_convert.py             |  57 +++++++++++++++++
 tests/test_cpython.py             | 103 ++++++++++++++++++++++++++++++
 tests/test_plain.py               |  42 ++++++++++++
 8 files changed, 281 insertions(+), 1 deletion(-)
 create mode 100644 docstring_to_markdown/_utils.py
 create mode 100644 docstring_to_markdown/cpython.py
 create mode 100644 docstring_to_markdown/plain.py
 create mode 100644 tests/test_convert.py
 create mode 100644 tests/test_cpython.py
 create mode 100644 tests/test_plain.py

diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index b4d0bdf..f778d47 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -1,4 +1,6 @@
+from .cpython import cpython_to_markdown
 from .google import google_to_markdown, looks_like_google
+from .plain import looks_like_plain_text, plain_text_to_markdown
 from .rst import looks_like_rst, rst_to_markdown
 
 __version__ = "0.13"
@@ -15,4 +17,11 @@ def convert(docstring: str) -> str:
     if looks_like_google(docstring):
         return google_to_markdown(docstring)
 
+    if looks_like_plain_text(docstring):
+        return plain_text_to_markdown(docstring)
+
+    cpython = cpython_to_markdown(docstring)
+    if cpython:
+        return cpython
+
     raise UnknownFormatError()
diff --git a/docstring_to_markdown/_utils.py b/docstring_to_markdown/_utils.py
new file mode 100644
index 0000000..847c699
--- /dev/null
+++ b/docstring_to_markdown/_utils.py
@@ -0,0 +1,5 @@
+from re import sub
+
+
+def escape_markdown(text: str) -> str:
+    return sub(r'([\\#*_[\]])', r'\\\1', text)
diff --git a/docstring_to_markdown/cpython.py b/docstring_to_markdown/cpython.py
new file mode 100644
index 0000000..e2cae78
--- /dev/null
+++ b/docstring_to_markdown/cpython.py
@@ -0,0 +1,37 @@
+from typing import Union, List
+from re import fullmatch
+
+from ._utils import escape_markdown
+
+def _is_cpython_signature_line(line: str) -> bool:
+    """CPython uses signature lines in the following format:
+
+    str(bytes_or_buffer[, encoding[, errors]]) -> str
+    """
+    return fullmatch(r'\w+\(\S*(, \S+)*(\[, \S+\])*\)\s--?>\s.+', line) is not None
+
+
+def cpython_to_markdown(text: str) -> Union[str, None]:
+    signature_lines: List[str] = []
+    other_lines: List[str] = []
+    for line in text.splitlines():
+        if not other_lines and _is_cpython_signature_line(line):
+            signature_lines.append(line)
+        elif not signature_lines:
+            return None
+        elif line.startswith('    '):
+            signature_lines.append(line)
+        else:
+            other_lines.append(line)
+    return '\n'.join([
+        '```',
+        '\n'.join(signature_lines),
+        '```',
+        escape_markdown('\n'.join(other_lines))
+    ])
+
+def looks_like_cpython(text: str) -> bool:
+    return cpython_to_markdown(text) is not None
+
+
+__all__ = ['looks_like_cpython', 'cpython_to_markdown']
diff --git a/docstring_to_markdown/plain.py b/docstring_to_markdown/plain.py
new file mode 100644
index 0000000..d3bf7fb
--- /dev/null
+++ b/docstring_to_markdown/plain.py
@@ -0,0 +1,27 @@
+from re import fullmatch
+from ._utils import escape_markdown
+
+
+def looks_like_plain_text(value: str) -> bool:
+    """Check if given string has plain text following English syntax without need for escaping.
+
+    Accepts:
+    - words without numbers
+    - full stop, bangs and question marks at the end of a word if followed by a space or end of string
+    - commas, colons and semicolons if after a word and followed by a space
+    - dashes between words (like in `e-mail`)
+    - double and single quotes if proceeded with a space and followed by a word, or if proceeded by a word and followed by a space (or end of string); single quotes are also allowed in between two words
+    - parentheses if opening preceded by space and closing followed by space or end
+
+    Does not accept:
+    - square brackets (used in markdown a lot)
+    """
+    if '_' in value:
+        return False
+    return fullmatch(r"((\w[\.!\?\)'\"](\s|$))|(\w[,:;]\s)|(\w[-']\w)|(\w\s['\"\(])|\w|\s)+", value) is not None
+
+
+def plain_text_to_markdown(text: str) -> str:
+    return escape_markdown(text)
+
+__all__ = ['looks_like_plain_text', 'plain_text_to_markdown']
diff --git a/setup.cfg b/setup.cfg
index 4b48e64..0bb013f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -37,7 +37,7 @@ docstring-to-markdown = py.typed
 addopts =
     --pyargs tests
     --cov docstring_to_markdown
-    --cov-fail-under=98
+    --cov-fail-under=99
     --cov-report term-missing:skip-covered
     -p no:warnings
     --flake8
diff --git a/tests/test_convert.py b/tests/test_convert.py
new file mode 100644
index 0000000..7642aeb
--- /dev/null
+++ b/tests/test_convert.py
@@ -0,0 +1,57 @@
+from docstring_to_markdown import convert, UnknownFormatError
+import pytest
+
+CPYTHON = """\
+bool(x) -> bool
+
+Returns True when the argument x is true, False otherwise.\
+"""
+
+
+CPYTHON_MD = """\
+```
+bool(x) -> bool
+```
+
+Returns True when the argument x is true, False otherwise.\
+"""
+
+GOOGLE = """Do **something**.
+
+Args:
+    a: some arg
+    b: some arg
+"""
+
+GOOGLE_MD = """Do **something**.
+
+#### Args
+
+- `a`: some arg
+- `b`: some arg
+"""
+
+
+RST = "Please see `this link<https://example.com>`__."
+RST_MD = "Please see [this link](https://example.com)."
+
+
+def test_convert_cpython():
+    assert convert(CPYTHON) == CPYTHON_MD
+
+
+def test_convert_plain_text():
+    assert convert('This is a sentence.') == 'This is a sentence.'
+
+
+def test_convert_google():
+    assert convert(GOOGLE) == GOOGLE_MD
+
+
+def test_convert_rst():
+    assert convert(RST) == RST_MD
+
+
+def test_unknown_format():
+    with pytest.raises(UnknownFormatError):
+        convert('ARGS [arg1, arg2] RETURNS: str OR None')
diff --git a/tests/test_cpython.py b/tests/test_cpython.py
new file mode 100644
index 0000000..2b7245d
--- /dev/null
+++ b/tests/test_cpython.py
@@ -0,0 +1,103 @@
+import pytest
+from docstring_to_markdown.cpython import looks_like_cpython, cpython_to_markdown
+
+BOOL = """\
+bool(x) -> bool
+
+Returns True when the argument x is true, False otherwise.\
+"""
+
+BOOL_MD = """\
+```
+bool(x) -> bool
+```
+
+Returns True when the argument x is true, False otherwise.\
+"""
+
+BYTES = """\
+bytes(iterable_of_ints) -> bytes
+bytes(string, encoding[, errors]) -> bytes
+bytes(bytes_or_buffer) -> immutable copy of bytes_or_buffer
+bytes(int) -> bytes object of size given by the parameter initialized with null bytes
+bytes() -> empty bytes object
+
+Construct an immutable array of bytes from:
+  - an iterable yielding integers in range(256)
+  - a text string encoded using the specified encoding
+  - any object implementing the buffer API.
+  - an integer\
+"""
+
+COLLECTIONS_DEQUEUE = """\
+deque([iterable[, maxlen]]) --> deque object
+
+A list-like sequence optimized for data accesses near its endpoints.\
+"""
+
+DICT = """\
+dict() -> new empty dictionary
+dict(mapping) -> new dictionary initialized from a mapping object's
+    (key, value) pairs
+dict(iterable) -> new dictionary initialized as if via:
+    d = {}
+    for k, v in iterable:
+        d[k] = v
+dict(**kwargs) -> new dictionary initialized with the name=value pairs
+    in the keyword argument list.  For example:  dict(one=1, two=2)\
+"""
+
+STR = """\
+str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.__str__() (if defined)
+or repr(object).\
+"""
+
+STR_MD = """\
+```
+str(object='') -> str
+str(bytes_or_buffer[, encoding[, errors]]) -> str
+```
+
+Create a new string object from the given object. If encoding or
+errors is specified, then the object must expose a data buffer
+that will be decoded using the given encoding and error handler.
+Otherwise, returns the result of object.\\_\\_str\\_\\_() (if defined)
+or repr(object).\
+"""
+
+
+@pytest.mark.parametrize("text", [BYTES, STR, DICT, BOOL, COLLECTIONS_DEQUEUE])
+def test_accepts_cpython_docstrings(text):
+    assert looks_like_cpython(text) is True
+
+
+@pytest.mark.parametrize("text", [
+    "[link label](https://link)",
+    "![image label](https://source)",
+    "Some **bold** text",
+    "More __bold__ text",
+    "Some *italic* text",
+    "More _italic_ text",
+    "This is a sentence.",
+    "Exclamation!",
+    "Can I ask a question?",
+    "Let's send an e-mail",
+    "Parentheses (are) fine (really)",
+    "Double \"quotes\" and single 'quotes'"
+])
+def test_rejects_markdown_and_plain_text(text):
+    assert looks_like_cpython(text) is False
+
+
+def test_conversion_bool():
+    assert cpython_to_markdown(BOOL) == BOOL_MD
+
+
+def test_conversion_str():
+    assert cpython_to_markdown(STR) == STR_MD
diff --git a/tests/test_plain.py b/tests/test_plain.py
new file mode 100644
index 0000000..61ef4b4
--- /dev/null
+++ b/tests/test_plain.py
@@ -0,0 +1,42 @@
+import pytest
+from docstring_to_markdown.plain import looks_like_plain_text, plain_text_to_markdown
+
+
+@pytest.mark.parametrize("text", [
+    "This is a sentence.",
+    "Exclamation!",
+    "Can I ask a question?",
+    "Let's send an e-mail",
+    "Parentheses (are) fine (really)",
+    "Double \"quotes\" and single 'quotes'"
+])
+def test_accepts_english(text):
+    assert looks_like_plain_text(text) is True
+
+
+@pytest.mark.parametrize("text", [
+    "[link label](https://link)",
+    "![image label](https://source)",
+    "Some **bold** text",
+    "More __bold__ text",
+    "Some *italic* text",
+    "More _italic_ text"
+])
+def test_rejects_markdown(text):
+    assert looks_like_plain_text(text) is False
+
+
+@pytest.mark.parametrize("text", [
+    "def test():",
+    "print(123)",
+    "func(arg)",
+    "2 + 2",
+    "var['test']",
+    "x = 'test'"
+])
+def test_rejects_code(text):
+    assert looks_like_plain_text(text) is False
+
+
+def test_conversion():
+    assert plain_text_to_markdown("test") == "test"

From 08286b6692b6376572ee01288d7ba7a6064ed88f Mon Sep 17 00:00:00 2001
From: krassowski <5832902+krassowski@users.noreply.github.com>
Date: Mon, 19 Feb 2024 15:26:25 +0000
Subject: [PATCH 12/19] Bump version to v0.14

---
 docstring_to_markdown/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index f778d47..317c724 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -3,7 +3,7 @@
 from .plain import looks_like_plain_text, plain_text_to_markdown
 from .rst import looks_like_rst, rst_to_markdown
 
-__version__ = "0.13"
+__version__ = "0.14"
 
 
 class UnknownFormatError(Exception):

From 5c36ac7bfb45bb660d01c71a61da6279628141c4 Mon Sep 17 00:00:00 2001
From: krassowski <5832902+krassowski@users.noreply.github.com>
Date: Wed, 21 Feb 2024 13:33:47 +0000
Subject: [PATCH 13/19] Fix multi-line links and incorrect dunder escapes in
 code

---
 docstring_to_markdown/__init__.py |  2 +-
 docstring_to_markdown/rst.py      |  8 ++++----
 tests/test_rst.py                 | 19 +++++++++++++++++++
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index 317c724..62fa804 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -3,7 +3,7 @@
 from .plain import looks_like_plain_text, plain_text_to_markdown
 from .rst import looks_like_rst, rst_to_markdown
 
-__version__ = "0.14"
+__version__ = "0.15"
 
 
 class UnknownFormatError(Exception):
diff --git a/docstring_to_markdown/rst.py b/docstring_to_markdown/rst.py
index 174f9de..ba50d91 100644
--- a/docstring_to_markdown/rst.py
+++ b/docstring_to_markdown/rst.py
@@ -1,13 +1,13 @@
 from abc import ABC, abstractmethod
 from enum import IntEnum, auto
 from types import SimpleNamespace
-from typing import Union, List, Dict
+from typing import Callable, Match, Union, List, Dict
 import re
 
 
 class Directive:
     def __init__(
-        self, pattern: str, replacement: str,
+        self, pattern: str, replacement: Union[str, Callable[[Match], str]],
         name: Union[str, None] = None,
         flags: int = 0
     ):
@@ -249,7 +249,7 @@ def inline_markdown(self):
     ),
     Directive(
         pattern=r'`(?P<label>[^<`]+?)(\n?)<(?P<url>[^>`]+)>`_+',
-        replacement=r'[\g<label>](\g<url>)'
+        replacement=lambda m: '[' + m.group('label') + '](' + re.sub(r"\s+", "", m.group('url')) + ')'
     ),
     Directive(
         pattern=r':mod:`(?P<label>[^`]+)`',
@@ -316,7 +316,7 @@ def inline_markdown(self):
 
 ESCAPING_RULES: List[Directive] = [
     Directive(
-        pattern=r'__(?P<text>\S+)__',
+        pattern=r'(?<!`)__(?P<text>\S+)__(?!`)',
         replacement=r'\_\_\g<text>\_\_'
     )
 ]
diff --git a/tests/test_rst.py b/tests/test_rst.py
index 93f89ac..3830563 100644
--- a/tests/test_rst.py
+++ b/tests/test_rst.py
@@ -78,6 +78,17 @@
     "[this link](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)."
 )
 
+RST_LINK_MULTILINE_EXAMPLE = """
+See
+`strftime documentation
+<https://docs.python.org/3/library/datetime.html
+#strftime-and-strptime-behavior>`_ for more.
+"""
+RST_LINK_MULTILINE_MARKDOWN = """
+See
+[strftime documentation](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior) for more.
+"""
+
 RST_REF_EXAMPLE = """See :ref:`here <timeseries.offset_aliases>` for a list of frequency aliases."""
 RST_REF_MARKDOWN = """See here: `timeseries.offset_aliases` for a list of frequency aliases."""
 
@@ -686,6 +697,10 @@ def foo():
         'rst': RST_LINK_EXAMPLE,
         'md': RST_LINK_EXAMPLE_MARKDOWN
     },
+    'converts multi-line links': {
+        'rst': RST_LINK_MULTILINE_EXAMPLE,
+        'md': RST_LINK_MULTILINE_MARKDOWN
+    },
     'changes highlight': {
         'rst': RST_HIGHLIGHTED_BLOCK,
         'md': RST_HIGHLIGHTED_BLOCK_MARKDOWN
@@ -764,6 +779,10 @@ def foo():
         'rst': '__init__',
         'md': r'\_\_init\_\_'
     },
+    'does not escape dunders in code': {
+        'rst': '`__init__`',
+        'md': '`__init__`'
+    },
     'converts bibliographic references': {
         'rst': REFERENCES,
         'md': REFERENCES_MARKDOWN

From 9e2277086187548406f089e1c7afb09a4552584c Mon Sep 17 00:00:00 2001
From: krassowski <5832902+krassowski@users.noreply.github.com>
Date: Wed, 21 Feb 2024 13:44:36 +0000
Subject: [PATCH 14/19] Testing: remove 3.6

---
 .github/workflows/tests.yml | 3 ---
 README.md                   | 2 +-
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 6ccb4e8..425eeff 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -12,9 +12,6 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: [3.7, 3.8, 3.9, '3.10', '3.11']
-        include:
-          - os: ubuntu-20.04
-            python-version: 3.6
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v2
diff --git a/README.md b/README.md
index 6cea177..7d7f45f 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 On the fly conversion of Python docstrings to markdown
 
-- Python 3.6+
+- Python 3.6+ (tested on 3.7 up to 3.11)
 - can recognise reStructuredText and convert multiple of its features to Markdown
 - since v0.13 includes initial support for Google-formatted docstrings
 

From 377c2bb36226c4b90aa9598727fde3eb079f6c00 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Krassowski?=
 <5832902+krassowski@users.noreply.github.com>
Date: Mon, 24 Mar 2025 12:25:37 +0000
Subject: [PATCH 15/19] Merge pull request #40 from krassowski/fix-actions

Drop Python 3.7 from testing, add 3.12 and 3.13, update actions
---
 .github/workflows/publish.yml |  8 ++++----
 .github/workflows/tests.yml   | 10 +++++-----
 README.md                     |  2 +-
 pyproject.toml                |  3 +++
 requirements-dev.txt          |  2 +-
 5 files changed, 14 insertions(+), 11 deletions(-)
 create mode 100644 pyproject.toml

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 7eb7355..bd46cb7 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -8,17 +8,17 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Python 3.8
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: 3.8
     - name: Install build dependencies
       run: |
-        python -m pip install --upgrade pip wheel
+        python -m pip install --upgrade pip wheel build
     - name: Build package
       run: |
-        python setup.py sdist bdist_wheel
+        python -m build
     - name: Publish a Python distribution to PyPI
       uses: pypa/gh-action-pypi-publish@v1.4.1
       with:
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 425eeff..7429365 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -11,17 +11,17 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.7, 3.8, 3.9, '3.10', '3.11']
+        python-version: [3.8, 3.9, '3.10', '3.11', '3.12', '3.13']
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install test dependencies
       run: |
-        python -m pip install --upgrade pip wheel
+        python -m pip install --upgrade pip wheel build
         python -m pip install -r requirements-dev.txt
     - name: Temporary installation
       run: python -m pip install -e .
@@ -33,7 +33,7 @@ jobs:
         mypy docstring_to_markdown
     - name: Build package
       run: |
-        python setup.py sdist bdist_wheel
+        python -m build
     - name: Install package
       run: python -m pip install --find-links=dist --no-index --ignore-installed docstring_to_markdown
     - name: Pip check
diff --git a/README.md b/README.md
index 7d7f45f..94231e4 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 On the fly conversion of Python docstrings to markdown
 
-- Python 3.6+ (tested on 3.7 up to 3.11)
+- Python 3.6+ (tested on 3.8 up to 3.13)
 - can recognise reStructuredText and convert multiple of its features to Markdown
 - since v0.13 includes initial support for Google-formatted docstrings
 
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..fed528d
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
diff --git a/requirements-dev.txt b/requirements-dev.txt
index 76d0c2c..d6df770 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -1,5 +1,5 @@
 pytest
 pytest-cov
 pytest-flake8
-flake8<5
+flake8
 mypy

From f443c2ea018e8763182c5c9e0a82d32dd67dc0cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Krassowski?=
 <5832902+krassowski@users.noreply.github.com>
Date: Tue, 25 Mar 2025 12:35:46 +0000
Subject: [PATCH 16/19] Implement entry points to allow extension/customization
 (#41)

* Implement entry points to allow extension/customization

Require Python 3.7 to use Protocol

Fix test coverage

* Bump version to 0.16
---
 .github/workflows/tests.yml       |  2 +-
 README.md                         |  7 ++-
 docstring_to_markdown/__init__.py | 62 ++++++++++++++++++-------
 docstring_to_markdown/cpython.py  | 25 ++++++++++-
 docstring_to_markdown/google.py   | 14 ++++++
 docstring_to_markdown/plain.py    | 15 ++++++-
 docstring_to_markdown/rst.py      | 19 +++++++-
 docstring_to_markdown/types.py    | 14 ++++++
 setup.cfg                         | 19 +++++++-
 tests/test_convert.py             | 75 +++++++++++++++++++++++++++++++
 tests/test_cpython.py             |  9 +++-
 tests/test_google.py              |  9 +++-
 tests/test_plain.py               |  9 +++-
 tests/test_rst.py                 | 57 ++++++++++++++++++++++-
 14 files changed, 309 insertions(+), 27 deletions(-)
 create mode 100644 docstring_to_markdown/types.py

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 7429365..8bd7e07 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -35,6 +35,6 @@ jobs:
       run: |
         python -m build
     - name: Install package
-      run: python -m pip install --find-links=dist --no-index --ignore-installed docstring_to_markdown
+      run: python -m pip install --find-links=dist --ignore-installed docstring_to_markdown
     - name: Pip check
       run: python -m pip check
diff --git a/README.md b/README.md
index 94231e4..97a3703 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 On the fly conversion of Python docstrings to markdown
 
-- Python 3.6+ (tested on 3.8 up to 3.13)
+- Python 3.7+ (tested on 3.8 up to 3.13)
 - can recognise reStructuredText and convert multiple of its features to Markdown
 - since v0.13 includes initial support for Google-formatted docstrings
 
@@ -35,6 +35,11 @@ Traceback (most recent call last):
 docstring_to_markdown.UnknownFormatError
 ```
 
+### Extensibility
+
+`docstring_to_markdown` entry point group allows to add custom converters which follow the `Converter` protocol.
+The built-in converters can be customized by providing entry point with matching name.
+
 ### Development
 
 ```bash
diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index 62fa804..a9367f0 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -1,27 +1,59 @@
-from .cpython import cpython_to_markdown
-from .google import google_to_markdown, looks_like_google
-from .plain import looks_like_plain_text, plain_text_to_markdown
-from .rst import looks_like_rst, rst_to_markdown
+from importlib_metadata import entry_points
+from typing import List, TYPE_CHECKING
 
-__version__ = "0.15"
+from .types import Converter
+
+if TYPE_CHECKING:
+    from importlib_metadata import EntryPoint
+
+__version__ = "0.16"
 
 
 class UnknownFormatError(Exception):
     pass
 
 
-def convert(docstring: str) -> str:
-    if looks_like_rst(docstring):
-        return rst_to_markdown(docstring)
+def _entry_points_sort_key(entry_point: 'EntryPoint'):
+    if entry_point.dist is None:
+        return 1
+    if entry_point.dist.name == "docstring-to-markdown":
+        return 0
+    return 1
+
+
+def _load_converters() -> List[Converter]:
+    converter_entry_points = entry_points(
+        group="docstring_to_markdown"
+    )
+    # sort so that the default ones can be overridden
+    sorted_entry_points = sorted(
+        converter_entry_points,
+        key=_entry_points_sort_key
+    )
+    # de-duplicate
+    unique_entry_points = {}
+    for entry_point in sorted_entry_points:
+        unique_entry_points[entry_point.name] = entry_point
 
-    if looks_like_google(docstring):
-        return google_to_markdown(docstring)
+    converters = []
+    for entry_point in unique_entry_points.values():
+        converter_class = entry_point.load()
+        converters.append(converter_class())
 
-    if looks_like_plain_text(docstring):
-        return plain_text_to_markdown(docstring)
+    converters.sort(key=lambda converter: -converter.priority)
 
-    cpython = cpython_to_markdown(docstring)
-    if cpython:
-        return cpython
+    return converters
+
+
+_CONVERTERS = None
+
+
+def convert(docstring: str) -> str:
+    global _CONVERTERS
+    if _CONVERTERS is None:
+        _CONVERTERS = _load_converters()
+    for converter in _CONVERTERS:
+        if converter.can_convert(docstring):
+            return converter.convert(docstring)
 
     raise UnknownFormatError()
diff --git a/docstring_to_markdown/cpython.py b/docstring_to_markdown/cpython.py
index e2cae78..974ea60 100644
--- a/docstring_to_markdown/cpython.py
+++ b/docstring_to_markdown/cpython.py
@@ -1,8 +1,10 @@
 from typing import Union, List
 from re import fullmatch
 
+from .types import Converter
 from ._utils import escape_markdown
 
+
 def _is_cpython_signature_line(line: str) -> bool:
     """CPython uses signature lines in the following format:
 
@@ -30,8 +32,29 @@ def cpython_to_markdown(text: str) -> Union[str, None]:
         escape_markdown('\n'.join(other_lines))
     ])
 
+
 def looks_like_cpython(text: str) -> bool:
     return cpython_to_markdown(text) is not None
 
 
-__all__ = ['looks_like_cpython', 'cpython_to_markdown']
+class CPythonConverter(Converter):
+
+    priority = 10
+
+    def __init__(self) -> None:
+        self._last_docstring: Union[str, None] = None
+        self._converted: Union[str, None] = None
+
+    def can_convert(self, docstring):
+        self._last_docstring = docstring
+        self._converted = cpython_to_markdown(docstring)
+        return self._converted is not None
+
+    def convert(self, docstring):
+        if docstring != self._last_docstring:
+            self._last_docstring = docstring
+            self._converted = cpython_to_markdown(docstring)
+        return self._converted
+
+
+__all__ = ['looks_like_cpython', 'cpython_to_markdown', 'CPythonConverter']
diff --git a/docstring_to_markdown/google.py b/docstring_to_markdown/google.py
index e3ca5a8..156f3da 100644
--- a/docstring_to_markdown/google.py
+++ b/docstring_to_markdown/google.py
@@ -2,6 +2,9 @@
 from textwrap import dedent
 from typing import List
 
+from .types import Converter
+
+
 # All possible sections in Google style docstrings
 SECTION_HEADERS: List[str] = [
     "Args",
@@ -169,3 +172,14 @@ def google_to_markdown(text: str, extract_signature: bool = True) -> str:
     docstring = GoogleDocstring(text)
 
     return docstring.as_markdown()
+
+
+class GoogleConverter(Converter):
+
+    priority = 75
+
+    def can_convert(self, docstring):
+        return looks_like_google(docstring)
+
+    def convert(self, docstring):
+        return google_to_markdown(docstring)
diff --git a/docstring_to_markdown/plain.py b/docstring_to_markdown/plain.py
index d3bf7fb..3c42253 100644
--- a/docstring_to_markdown/plain.py
+++ b/docstring_to_markdown/plain.py
@@ -1,4 +1,5 @@
 from re import fullmatch
+from .types import Converter
 from ._utils import escape_markdown
 
 
@@ -24,4 +25,16 @@ def looks_like_plain_text(value: str) -> bool:
 def plain_text_to_markdown(text: str) -> str:
     return escape_markdown(text)
 
-__all__ = ['looks_like_plain_text', 'plain_text_to_markdown']
+
+class PlainTextConverter(Converter):
+
+    priority = 50
+
+    def can_convert(self, docstring):
+        return looks_like_plain_text(docstring)
+
+    def convert(self, docstring):
+        return plain_text_to_markdown(docstring)
+
+
+__all__ = ['looks_like_plain_text', 'plain_text_to_markdown', 'PlainTextConverter']
diff --git a/docstring_to_markdown/rst.py b/docstring_to_markdown/rst.py
index ba50d91..4149773 100644
--- a/docstring_to_markdown/rst.py
+++ b/docstring_to_markdown/rst.py
@@ -4,6 +4,8 @@
 from typing import Callable, Match, Union, List, Dict
 import re
 
+from .types import Converter
+
 
 class Directive:
     def __init__(
@@ -532,7 +534,7 @@ def _consume_row(self, line: str):
                 self._rows.append(self._split(line))
             self._expecting_row_content = not self._expecting_row_content
         else:
-            self._state += 1
+            self._state += 1    # pragma: no cover
 
 
 class BlockParser(IParser):
@@ -651,11 +653,13 @@ def initiate_parsing(self, line: str, current_language: str):
         if line.strip() == '.. autosummary::':
             language = ''
             line = ''
+            suffix = ''
         else:
             line = re.sub(r'::$', '', line)
+            suffix = '\n\n'
 
         self._start_block(language)
-        return IBlockBeginning(remainder=line.rstrip() + '\n\n')
+        return IBlockBeginning(remainder=line.rstrip() + suffix)
 
 
 class MathBlockParser(IndentedBlockParser):
@@ -825,3 +829,14 @@ def flush_buffer():
     if active_parser:
         markdown += active_parser.finish_consumption(True)
     return markdown
+
+
+class ReStructuredTextConverter(Converter):
+
+    priority = 100
+
+    def can_convert(self, docstring):
+        return looks_like_rst(docstring)
+
+    def convert(self, docstring):
+        return rst_to_markdown(docstring)
diff --git a/docstring_to_markdown/types.py b/docstring_to_markdown/types.py
new file mode 100644
index 0000000..ef7fb18
--- /dev/null
+++ b/docstring_to_markdown/types.py
@@ -0,0 +1,14 @@
+from typing_extensions import Protocol
+
+
+class Converter(Protocol):
+
+    def convert(self, docstring: str) -> str:
+        """Convert given docstring to markdown."""
+
+    def can_convert(self, docstring: str) -> bool:
+        """Check if conversion to markdown can be performed."""
+
+    # The higher the priority, the sooner the conversion
+    # with this converter will be attempted.
+    priority: int
diff --git a/setup.cfg b/setup.cfg
index 0bb013f..817ea9e 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -28,21 +28,36 @@ warn_unused_configs = True
 
 [options]
 packages = find:
-python_requires = >=3.6
+python_requires = >=3.7
+install_requires =
+    importlib-metadata>=3.6
+    typing_extensions>=4.6
 
 [options.package_data]
 docstring-to-markdown = py.typed
 
+[options.entry_points]
+docstring_to_markdown =
+  rst = docstring_to_markdown.rst:ReStructuredTextConverter
+  google = docstring_to_markdown.google:GoogleConverter
+  plain = docstring_to_markdown.plain:PlainTextConverter
+  cpython = docstring_to_markdown.cpython:CPythonConverter
+
 [tool:pytest]
 addopts =
     --pyargs tests
     --cov docstring_to_markdown
-    --cov-fail-under=99
+    --cov-fail-under=100
     --cov-report term-missing:skip-covered
     -p no:warnings
     --flake8
     -vv
 
+[coverage:report]
+exclude_lines =
+    pragma: no cover
+    if TYPE_CHECKING:
+
 [flake8]
 max-line-length = 120
 max-complexity = 15
diff --git a/tests/test_convert.py b/tests/test_convert.py
index 7642aeb..5b030da 100644
--- a/tests/test_convert.py
+++ b/tests/test_convert.py
@@ -1,4 +1,10 @@
+from contextlib import contextmanager
 from docstring_to_markdown import convert, UnknownFormatError
+from docstring_to_markdown.types import Converter
+from docstring_to_markdown.cpython import CPythonConverter
+from importlib_metadata import EntryPoint, entry_points, distribution
+from unittest.mock import patch
+import docstring_to_markdown
 import pytest
 
 CPYTHON = """\
@@ -55,3 +61,72 @@ def test_convert_rst():
 def test_unknown_format():
     with pytest.raises(UnknownFormatError):
         convert('ARGS [arg1, arg2] RETURNS: str OR None')
+
+
+class HighPriorityConverter(Converter):
+    priority = 120
+
+    def convert(self, docstring):
+        return "HighPriority"
+
+    def can_convert(self, docstring):
+        return True
+
+
+class MockEntryPoint(EntryPoint):
+    def load(self):
+        return self.value
+
+    dist = None
+
+
+class DistMockEntryPoint(MockEntryPoint):
+    # Pretend it is contributed by `pytest`.
+    # It could be anything else, but `pytest`
+    # is guaranteed to be installed during tests.
+    dist = distribution('pytest')
+
+
+class CustomCPythonConverter(CPythonConverter):
+    priority = 10
+
+    def convert(self, docstring):
+        return 'CustomCPython'
+
+    def can_convert(self, docstring):
+        return True
+
+
+@contextmanager
+def custom_entry_points(entry_points):
+    old = docstring_to_markdown._CONVERTERS
+    docstring_to_markdown._CONVERTERS = None
+    with patch.object(docstring_to_markdown, 'entry_points', return_value=entry_points):
+        yield
+    docstring_to_markdown._CONVERTERS = old
+
+
+def test_adding_entry_point():
+    original_entry_points = entry_points(group="docstring_to_markdown")
+    mock_entry_point = MockEntryPoint(
+        name='high-priority-converter',
+        group='docstring_to_markdown',
+        value=HighPriorityConverter,
+    )
+    with custom_entry_points([*original_entry_points, mock_entry_point]):
+        assert convert('test') == 'HighPriority'
+
+
+def test_replacing_entry_point():
+    assert convert(CPYTHON) == CPYTHON_MD
+    original_entry_points = entry_points(group="docstring_to_markdown")
+    mock_entry_point = DistMockEntryPoint(
+        name='cpython',
+        group='docstring_to_markdown',
+        value=CustomCPythonConverter
+    )
+    with custom_entry_points([*original_entry_points, mock_entry_point]):
+        assert convert('test') == 'test'
+        assert convert(GOOGLE) == GOOGLE_MD
+        assert convert(RST) == RST_MD
+        assert convert(CPYTHON) == 'CustomCPython'
diff --git a/tests/test_cpython.py b/tests/test_cpython.py
index 2b7245d..b292c66 100644
--- a/tests/test_cpython.py
+++ b/tests/test_cpython.py
@@ -1,5 +1,5 @@
 import pytest
-from docstring_to_markdown.cpython import looks_like_cpython, cpython_to_markdown
+from docstring_to_markdown.cpython import looks_like_cpython, cpython_to_markdown, CPythonConverter
 
 BOOL = """\
 bool(x) -> bool
@@ -101,3 +101,10 @@ def test_conversion_bool():
 
 def test_conversion_str():
     assert cpython_to_markdown(STR) == STR_MD
+
+
+def test_convert():
+    converter = CPythonConverter()
+    assert converter.can_convert(BOOL)
+    assert not converter.can_convert('this is plain text')
+    assert converter.convert(BOOL) == BOOL_MD
diff --git a/tests/test_google.py b/tests/test_google.py
index 78486bc..ef0d785 100644
--- a/tests/test_google.py
+++ b/tests/test_google.py
@@ -1,6 +1,6 @@
 import pytest
 
-from docstring_to_markdown.google import google_to_markdown, looks_like_google
+from docstring_to_markdown.google import google_to_markdown, looks_like_google, GoogleConverter
 
 BASIC_EXAMPLE = """Do **something**.
 
@@ -133,3 +133,10 @@ def test_looks_like_google_ignores_plain_text():
 )
 def test_google_to_markdown(google, markdown):
     assert google_to_markdown(google) == markdown
+
+
+def test_converter():
+    converter = GoogleConverter()
+    assert converter.can_convert(BASIC_EXAMPLE)
+    assert not converter.can_convert("This is plain text")
+    assert converter.convert(BASIC_EXAMPLE) == BASIC_EXAMPLE_MD
diff --git a/tests/test_plain.py b/tests/test_plain.py
index 61ef4b4..0e30eef 100644
--- a/tests/test_plain.py
+++ b/tests/test_plain.py
@@ -1,5 +1,5 @@
 import pytest
-from docstring_to_markdown.plain import looks_like_plain_text, plain_text_to_markdown
+from docstring_to_markdown.plain import looks_like_plain_text, plain_text_to_markdown, PlainTextConverter
 
 
 @pytest.mark.parametrize("text", [
@@ -40,3 +40,10 @@ def test_rejects_code(text):
 
 def test_conversion():
     assert plain_text_to_markdown("test") == "test"
+
+
+def test_convert():
+    converter = PlainTextConverter()
+    assert not converter.can_convert('def test():')
+    assert converter.can_convert('this is plain text')
+    assert converter.convert('test') == 'test'
diff --git a/tests/test_rst.py b/tests/test_rst.py
index 3830563..c645def 100644
--- a/tests/test_rst.py
+++ b/tests/test_rst.py
@@ -1,6 +1,6 @@
 import pytest
 
-from docstring_to_markdown.rst import looks_like_rst, rst_to_markdown
+from docstring_to_markdown.rst import looks_like_rst, rst_to_markdown, ReStructuredTextConverter
 
 
 SEE_ALSO = """
@@ -119,6 +119,26 @@
 A function definition is an executable statement.
 """
 
+RST_AUTOSUMMARY_BLOCK = """
+Summary
+
+.. autosummary::
+
+   environment.BuildEnvironment
+   util.relative_uri
+"""
+
+
+RST_AUTOSUMMARY_BLOCK_MARKDOWN = """
+Summary
+
+```
+environment.BuildEnvironment
+util.relative_uri
+```
+"""
+
+
 RST_COLON_CODE_BLOCK = """
 For example, the following code ::
 
@@ -598,6 +618,26 @@ def func(): pass
 """
 
 
+BROKEN_GRID_TABLE = """
++------------+-----------+------------+-----------------+---+---------+
+|param_kernel|param_gamma|param_degree|split0_test_score|...|rank_t...|
++============+===========+============+=================+===+=========+
+|  'poly'    |     --    |      2     |       0.80      |...|    2    |
++------------+-----------+------------+-----------------+---+---------+
+|  'poly'    |     --    |      3     |       0.70      |...|    4    |
+someone forgot to close the row above.
+"""
+
+
+BROKEN_GRID_TABLE_MARKDOWN = """
+| param_kernel | param_gamma | param_degree | split0_test_score | ... | rank_t... |
+| ------------ | ----------- | ------------ | ----------------- | --- | --------- |
+| 'poly'       | --          | 2            | 0.80              | ... | 2         |
+| 'poly'       | --          | 3            | 0.70              | ... | 4         |
+someone forgot to close the row above.
+"""
+
+
 NESTED_PARAMETERS = """
 Parameters
 ----------
@@ -733,6 +773,10 @@ def foo():
         'rst': NUMPY_EXAMPLE,
         'md': NUMPY_EXAMPLE_MARKDOWN
     },
+    'converts autosummary block': {
+        'rst': RST_AUTOSUMMARY_BLOCK,
+        'md': RST_AUTOSUMMARY_BLOCK_MARKDOWN
+    },
     'converts version changed': {
         'rst': '.. versionchanged:: 0.23.0',
         'md': '*Changed in 0.23.0*'
@@ -835,6 +879,10 @@ def foo():
         'rst': GRID_TABLE_IN_SKLEARN,
         'md': GRID_TABLE_IN_SKLEARN_MARKDOWN
     },
+    'converts broken grid table': {
+        'rst': BROKEN_GRID_TABLE,
+        'md': BROKEN_GRID_TABLE_MARKDOWN
+    },
     'converts nested parameter lists': {
         'rst': NESTED_PARAMETERS,
         'md': NESTED_PARAMETERS_MARKDOWN
@@ -888,3 +936,10 @@ def test_rst_to_markdown(rst, markdown):
     converted = rst_to_markdown(rst)
     print(converted)
     assert converted == markdown
+
+
+def test_converter():
+    converter = ReStructuredTextConverter()
+    assert converter.can_convert('.. versionadded:: 0.1')
+    assert not converter.can_convert('this is plain text')
+    assert converter.convert(PEP_287_CODE_BLOCK) == PEP_287_CODE_BLOCK_MARKDOWN

From f12c3373cebea0d581e2a6764dde8dc114a936a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Krassowski?=
 <5832902+krassowski@users.noreply.github.com>
Date: Thu, 1 May 2025 23:18:26 +0100
Subject: [PATCH 17/19] Fix test failures with `importlib-metadata` 8.7.0 (#43)

* Attempt to fix test failures with `importlib-metadata` 8.7.0
---
 tests/test_convert.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/test_convert.py b/tests/test_convert.py
index 5b030da..725951f 100644
--- a/tests/test_convert.py
+++ b/tests/test_convert.py
@@ -75,7 +75,7 @@ def can_convert(self, docstring):
 
 class MockEntryPoint(EntryPoint):
     def load(self):
-        return self.value
+        return globals()[self.attr]
 
     dist = None
 
@@ -111,7 +111,7 @@ def test_adding_entry_point():
     mock_entry_point = MockEntryPoint(
         name='high-priority-converter',
         group='docstring_to_markdown',
-        value=HighPriorityConverter,
+        value="here:HighPriorityConverter",
     )
     with custom_entry_points([*original_entry_points, mock_entry_point]):
         assert convert('test') == 'HighPriority'
@@ -123,7 +123,7 @@ def test_replacing_entry_point():
     mock_entry_point = DistMockEntryPoint(
         name='cpython',
         group='docstring_to_markdown',
-        value=CustomCPythonConverter
+        value="here:CustomCPythonConverter",
     )
     with custom_entry_points([*original_entry_points, mock_entry_point]):
         assert convert('test') == 'test'

From e3f944fad91fdba3de1c5345d9d79a1c88e27aaa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Krassowski?=
 <5832902+krassowski@users.noreply.github.com>
Date: Fri, 2 May 2025 15:26:09 +0100
Subject: [PATCH 18/19] Fix RsT edge cases to better support `polars` (#44)

* Fix a number of edge cases for polars docstrings

* Bump version
---
 docstring_to_markdown/__init__.py |   2 +-
 docstring_to_markdown/rst.py      |  39 +++++++--
 tests/test_rst.py                 | 127 +++++++++++++++++++++++++++++-
 3 files changed, 161 insertions(+), 7 deletions(-)

diff --git a/docstring_to_markdown/__init__.py b/docstring_to_markdown/__init__.py
index a9367f0..a70ed84 100644
--- a/docstring_to_markdown/__init__.py
+++ b/docstring_to_markdown/__init__.py
@@ -6,7 +6,7 @@
 if TYPE_CHECKING:
     from importlib_metadata import EntryPoint
 
-__version__ = "0.16"
+__version__ = "0.17"
 
 
 class UnknownFormatError(Exception):
diff --git a/docstring_to_markdown/rst.py b/docstring_to_markdown/rst.py
index 4149773..040b26d 100644
--- a/docstring_to_markdown/rst.py
+++ b/docstring_to_markdown/rst.py
@@ -1,5 +1,6 @@
 from abc import ABC, abstractmethod
 from enum import IntEnum, auto
+from textwrap import dedent
 from types import SimpleNamespace
 from typing import Callable, Match, Union, List, Dict
 import re
@@ -299,8 +300,8 @@ def inline_markdown(self):
 SECTION_DIRECTIVES: Dict[str, List[Directive]] = {
     'Parameters': [
         Directive(
-            pattern=r'^(?P<other_args>\*\*kwargs|\*args)$',
-            replacement=r'- `\g<other_args>`'
+            pattern=r'^(?P<other_args>(\w[\w\d_\.]*)|\*\*kwargs|\*args)$',
+            replacement=r'- `\g<other_args>`:'
         ),
         Directive(
             pattern=r'^(?P<arg1>[^:\s]+\d), (?P<arg2>[^:\s]+\d), \.\.\. : (?P<type>.+)$',
@@ -336,6 +337,7 @@ def _find_directive_pattern(name: str):
 
 
 def looks_like_rst(value: str) -> bool:
+    value = dedent(value)
     # check if any of the characteristic sections (and the properly formatted underline) is there
     for section in _RST_SECTIONS:
         if (section + '\n' + '-' * len(section) + '\n') in value:
@@ -542,10 +544,20 @@ class BlockParser(IParser):
     follower: Union['IParser', None] = None
     _buffer: List[str]
     _block_started: bool
+    _indent: Union[int, None]
+    should_measure_indent = True
 
     def __init__(self):
         self._buffer = []
         self._block_started = False
+        self._indent = None
+
+    def measure_indent(self, line: str):
+        line_indent = len(line) - len(line.lstrip())
+        if self._indent is None:
+            self._indent = line_indent
+        else:
+            self._indent = min(line_indent, self._indent)
 
     @abstractmethod
     def can_parse(self, line: str) -> bool:
@@ -558,6 +570,8 @@ def _start_block(self, language: str):
     def consume(self, line: str):
         if not self._block_started:
             raise ValueError('Block has not started')   # pragma: no cover
+        if self.should_measure_indent:
+            self.measure_indent(line)
         self._buffer.append(line)
 
     def finish_consumption(self, final: bool) -> str:
@@ -565,17 +579,24 @@ def finish_consumption(self, final: bool) -> str:
         if self._buffer[len(self._buffer) - 1].strip() == '':
             self._buffer.pop()
         self._buffer.append(self.enclosure + '\n')
-        result = '\n'.join(self._buffer)
+        indent = " " * (self._indent or 0)
+        intermediate = '\n'.join(self._buffer)
+        result = '\n'.join([
+            (indent + line) if line else line
+            for line in intermediate.splitlines()
+        ]) if indent else intermediate
         if not final:
             result += '\n'
         self._buffer = []
         self._block_started = False
+        self._indent = None
         return result
 
 
 class IndentedBlockParser(BlockParser, ABC):
     _is_block_beginning: bool
     _block_indent_size: Union[int, None]
+    should_measure_indent = False
 
     def __init__(self):
         super(IndentedBlockParser, self).__init__()
@@ -599,6 +620,7 @@ def consume(self, line: str):
                 return
         if self._block_indent_size is None:
             self._block_indent_size = len(line) - len(line.lstrip())
+        self.measure_indent(line)
         super().consume(line[self._block_indent_size:])
 
     def finish_consumption(self, final: bool) -> str:
@@ -684,6 +706,7 @@ def can_parse(self, line: str):
         return line.strip() in self.directives
 
     def initiate_parsing(self, line: str, current_language: str):
+        self.measure_indent(line)
         admonition = self.directives[line.strip()]
         self._start_block(f'\n{admonition.block_markdown}\n')
         return IBlockBeginning(remainder='')
@@ -694,6 +717,7 @@ def can_parse(self, line: str) -> bool:
         return re.match(CODE_BLOCK_PATTERN, line) is not None
 
     def initiate_parsing(self, line: str, current_language: str) -> IBlockBeginning:
+        self.measure_indent(line)
         match = re.match(CODE_BLOCK_PATTERN, line)
         # already checked in can_parse
         assert match
@@ -753,6 +777,8 @@ def rst_to_markdown(text: str, extract_signature: bool = True) -> str:
     most_recent_section: Union[str, None] = None
     is_first_line = True
 
+    text = dedent(text)
+
     def flush_buffer():
         nonlocal lines_buffer
         lines = '\n'.join(lines_buffer)
@@ -766,7 +792,8 @@ def flush_buffer():
         lines_buffer = []
         return lines
 
-    for line in text.split('\n'):
+    lines = text.split('\n')
+    for i, line in enumerate(lines):
         if is_first_line:
             if extract_signature:
                 signature_match = re.match(r'^(?P<name>\S+)\((?P<params>.*)\)$', line)
@@ -809,7 +836,9 @@ def flush_buffer():
             else:
                 if most_recent_section in SECTION_DIRECTIVES:
                     for section_directive in SECTION_DIRECTIVES[most_recent_section]:
-                        if re.match(section_directive.pattern, trimmed_line):
+                        next_line = lines[i + 1] if i + 1 < len(lines) else ""
+                        is_next_line_section = set(next_line.strip()) == {"-"}
+                        if re.match(section_directive.pattern, line) and not is_next_line_section:
                             line = re.sub(section_directive.pattern, section_directive.replacement, trimmed_line)
                             break
                 if trimmed_line.rstrip() in RST_SECTIONS:
diff --git a/tests/test_rst.py b/tests/test_rst.py
index c645def..4bafe26 100644
--- a/tests/test_rst.py
+++ b/tests/test_rst.py
@@ -337,7 +337,7 @@ def func(): pass
 
 - `x`: array_like
     Input array.
-- `**kwargs`
+- `**kwargs`:
     For other keyword-only arguments, see the ufunc docs.
 """
 
@@ -638,6 +638,119 @@ def func(): pass
 """
 
 
+# this format is often used by polars
+PARAMETERS_WITHOUT_TYPE = """
+Parameters
+----------
+source
+    Path(s) to a file or directory
+    When needing to authenticate for scanning cloud locations, see the
+    `storage_options` parameter.
+columns
+    Columns to select. Accepts a list of column indices (starting at zero) or a list
+    of column names.
+n_rows
+    Stop reading from parquet file after reading `n_rows`.
+    Only valid when `use_pyarrow=False`.
+
+Returns
+-------
+DataFrame
+"""
+
+PARAMETERS_WITHOUT_TYPE_MARKDOWN = """
+#### Parameters
+
+- `source`:
+    Path(s) to a file or directory
+    When needing to authenticate for scanning cloud locations, see the
+    `storage_options` parameter.
+- `columns`:
+    Columns to select. Accepts a list of column indices (starting at zero) or a list
+    of column names.
+- `n_rows`:
+    Stop reading from parquet file after reading `n_rows`.
+    Only valid when `use_pyarrow=False`.
+
+#### Returns
+
+DataFrame
+"""
+
+INDENTED_DOCSTRING = """
+    Parameters
+    ----------
+    glob
+        Expand path given via globbing rules.
+"""
+
+INDENTED_DOCSTRING_MARKDOWN = """
+#### Parameters
+
+- `glob`:
+    Expand path given via globbing rules.
+"""
+
+
+WARNINGS_IN_PARAMETERS = """
+Parameters
+----------
+glob
+    Expand path given via globbing rules.
+schema
+    Specify the datatypes of the columns. The datatypes must match the
+    datatypes in the file(s). If there are extra columns that are not in the
+    file(s), consider also enabling `allow_missing_columns`.
+
+    .. warning::
+        This functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+hive_schema
+    The column names and data types of the columns by which the data is partitioned.
+    If set to `None` (default), the schema of the Hive partitions is inferred.
+
+    .. warning::
+        This functionality is considered **unstable**. It may be changed
+        at any point without it being considered a breaking change.
+try_parse_hive_dates
+    Whether to try parsing hive values as date/datetime types.
+"""
+
+
+WARNINGS_IN_PARAMETERS_MARKDOWN = """
+#### Parameters
+
+- `glob`:
+    Expand path given via globbing rules.
+- `schema`:
+    Specify the datatypes of the columns. The datatypes must match the
+    datatypes in the file(s). If there are extra columns that are not in the
+    file(s), consider also enabling `allow_missing_columns`.
+
+
+    ---
+    ⚠️  **Warning**
+
+    This functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+
+    ---
+- `hive_schema`:
+    The column names and data types of the columns by which the data is partitioned.
+    If set to `None` (default), the schema of the Hive partitions is inferred.
+
+
+    ---
+    ⚠️  **Warning**
+
+    This functionality is considered **unstable**. It may be changed
+    at any point without it being considered a breaking change.
+
+    ---
+- `try_parse_hive_dates`:
+    Whether to try parsing hive values as date/datetime types.
+"""
+
 NESTED_PARAMETERS = """
 Parameters
 ----------
@@ -887,6 +1000,18 @@ def foo():
         'rst': NESTED_PARAMETERS,
         'md': NESTED_PARAMETERS_MARKDOWN
     },
+    'converts parameter without type': {
+        'rst': PARAMETERS_WITHOUT_TYPE,
+        'md': PARAMETERS_WITHOUT_TYPE_MARKDOWN
+    },
+    'converts indented parameters lists': {
+        'rst': INDENTED_DOCSTRING,
+        'md': INDENTED_DOCSTRING_MARKDOWN
+    },
+    'converts warnings in parameters lists': {
+        'rst': WARNINGS_IN_PARAMETERS,
+        'md': WARNINGS_IN_PARAMETERS_MARKDOWN
+    },
     'converts sphinx signatures': {
         'rst': SPHINX_SIGNATURE,
         'md': SPHINX_SIGNATURE_MARKDOWN

From 1cdc9e13d5d2ac6837c106a84d2eb638a2be8220 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Krassowski?=
 <5832902+krassowski@users.noreply.github.com>
Date: Fri, 2 May 2025 16:07:43 +0100
Subject: [PATCH 19/19] Use trusted publishing for package uploads (#45)

* Use trusted publishing for package uploads
---
 .github/workflows/publish.yml | 32 ++++++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index bd46cb7..9ad7f68 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -5,23 +5,39 @@ on:
     types: [created]
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.8
+    - name: Set up Python 3.9
       uses: actions/setup-python@v5
       with:
-        python-version: 3.8
+        python-version: 3.9
     - name: Install build dependencies
       run: |
         python -m pip install --upgrade pip wheel build
     - name: Build package
       run: |
         python -m build
-    - name: Publish a Python distribution to PyPI
-      uses: pypa/gh-action-pypi-publish@v1.4.1
+    - name: Upload Artifact
+      uses: actions/upload-artifact@v4
       with:
-        user: __token__
-        password: ${{ secrets.PYPI_UPLOAD_API_TOKEN }}
-
+        name: docstring-to-markdown dist ${{ github.run_number }}
+        path: ./dist
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    needs: [build]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/docstring-to-markdown
+    permissions:
+      id-token: write
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: docstring-to-markdown dist ${{ github.run_number }}
+        path: ./dist
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1