sphinx-markdown-builder icon indicating copy to clipboard operation
sphinx-markdown-builder copied to clipboard

[BUG] Asterisk (*) in overloaded function signatures omitted in Markdown output

Open ayeshasaeed665 opened this issue 2 months ago • 0 comments

Describe the bug A clear and concise description of what the bug is. When documenting functions with multiple @overload signatures, the * symbol in the rendered md files are omitted and it gives the following warning.

WARNING: unknown node type: <abbreviation: <#text: '*'>>

The function signatures are displayed correctly on html.

Steps to Reproduce

1. Create the test module

Create a file named test.py with the following contents:


    @overload
    def create(self, *, username: str, email: str, data: RequestData) -> str:
        ...

    @overload
    def create(self, *, job_id: str, data: JobData) -> JobResult:
        ...

    def create(
        self,
        *,
        username: Optional[str] = None,
        email: Optional[str] = None,
        job_id: Optional[str] = None,
        data: Optional[object] = None,
    ):
  

2. Install required packages

pip install sphinx sphinx-markdown-builder

3. Generate Sphinx scaffolding

Run the following command to create the Sphinx documentation structure (including Markdown builder):

sphinx-apidoc -o docs . -a --extensions sphinx_markdown_builder --full

This generates a docs/ directory with configuration files and reStructuredText sources.


4. Build the documentation

Change into the documentation directory and build the Markdown output:

cd docs && make markdown

5. Check the generated Markdown file

After the build completes, open the generated file:

docs/_build/markdown/test.md

This file contains the rendered documentation for test.py.

#### create(, username: str, email: str, data: [RequestData](#test.RequestData)) → str

#### create(, job_id: str, data: [JobData](#test.JobData)) → [JobResult](#test.JobResult)

Expected behavior A clear and concise description of what you expected to happen. These lines should instead render as

#### create(*, username: str, email: str, data: [RequestData](#test.RequestData)) → str

#### create(*, job_id: str, data: [JobData](#test.JobData)) → [JobResult](#test.JobResult)

The html build correctly displays the aesteriks

Image

Environment (please complete the following information):

  • OS: Ubuntu
  • Version sphinx-markdown-builder>=0.6.8

Additional context Add any other context about the problem here.

ayeshasaeed665 avatar Oct 17 '25 15:10 ayeshasaeed665