{"id":3979,"library":"docstring-to-markdown","title":"Docstring to Markdown Converter","description":"The `docstring-to-markdown` library provides on-the-fly conversion of Python docstrings into Markdown format. It currently supports reStructuredText and has initial support for Google-formatted docstrings since version 0.13. The current version is 0.17, and it is actively maintained with a regular release cadence as evidenced by its release history on PyPI.","status":"active","version":"0.17","language":"en","source_language":"en","source_url":"https://github.com/python-lsp/docstring-to-markdown","tags":["docstrings","markdown","documentation","reStructuredText","google-style"],"install":[{"cmd":"pip install docstring-to-markdown","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary conversion functionality is exposed as a top-level `convert` function directly within the `docstring_to_markdown` module, not through a class.","wrong":"from docstring_to_markdown import DocstringToMarkdownConverter","symbol":"convert","correct":"import docstring_to_markdown\nmarkdown_output = docstring_to_markdown.convert(docstring_content)"},{"note":"This exception is raised when the input docstring format cannot be recognized by the converter.","symbol":"UnknownFormatError","correct":"from docstring_to_markdown import UnknownFormatError"}],"quickstart":{"code":"import docstring_to_markdown\n\ndef my_function_rst(param1, param2):\n    \"\"\"\n    My function in reStructuredText format.\n\n    :param param1: The first parameter.\n    :type param1: str\n    :param param2: The second parameter.\n    :type param2: int\n    :returns: A concatenated string.\n    :rtype: str\n\n    .. code-block:: python\n\n        print('Example usage')\n\n    \"\"\"\n    return f\"{param1}-{param2}\"\n\ndef my_function_google(param1, param2):\n    \"\"\"\n    My function in Google style format.\n\n    Args:\n        param1 (str): The first parameter.\n        param2 (int): The second parameter.\n\n    Returns:\n        str: A concatenated string.\n\n    Example:\n        >>> my_function_google('hello', 123)\n        'hello-123'\n    \"\"\"\n    return f\"{param1}-{param2}\"\n\n\n# Convert a reStructuredText docstring\npython_code = my_function_rst.__doc__\nmarkdown_output = docstring_to_markdown.convert(python_code)\nprint(f\"ReStructuredText to Markdown:\\n{markdown_output}\\n\")\n\n# Convert a Google-style docstring\npython_code_google = my_function_google.__doc__\nmarkdown_output_google = docstring_to_markdown.convert(python_code_google)\nprint(f\"Google style to Markdown:\\n{markdown_output_google}\")\n\n# Example of an unrecognised format raising an error\ntry:\n    docstring_to_markdown.convert('This is a plain docstring without a recognized format.')\nexcept docstring_to_markdown.UnknownFormatError:\n    print(\"Successfully caught UnknownFormatError for unrecognized format.\")\n","lang":"python","description":"This quickstart demonstrates how to use `docstring_to_markdown.convert` to transform both reStructuredText and Google-style Python docstrings into Markdown. It also shows how to handle `UnknownFormatError` for unrecognised input."},"warnings":[{"fix":"Format docstrings using recognized styles (reStructuredText or Google-style) or implement a custom converter via the extensibility entry point.","message":"The `convert` function raises `UnknownFormatError` if it cannot recognize the format of the input docstring. Ensure your docstrings adhere to either reStructuredText or Google-style conventions for successful conversion.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Manually extract docstrings (e.g., using `__doc__` attribute or `inspect` module) before passing them to `docstring_to_markdown.convert`.","message":"The library primarily operates on docstring strings. It does not parse full Python source files to extract docstrings; you must provide the docstring content as a string to the `convert` function.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Test the output for complex docstrings and simplify the docstring formatting if the generated Markdown is not as expected. For highly complex documentation needs, consider dedicated documentation generators like Sphinx with Markdown extensions.","message":"While supporting reStructuredText and Google-style, the conversion might not cover all intricate features or edge cases of these formats perfectly, especially for highly complex or custom directives. The conversion aims for 'on the fly' utility, not necessarily full fidelity for all Sphinx-like capabilities.","severity":"gotcha","affected_versions":">=0.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}