search

liran-funaro / sphinx-markdown-builder

A Sphinx extension to add markdown generation support.
https://pypi.org/project/sphinx-markdown-builder
MIT License
32 stars 14 forks source link

Formatting error for typed attribute docstrings #6

Closed ttesileanu closed 4 months ago

ttesileanu commented 9 months ago

Attributes that have type information lead to wrongly formatted outputs, e.g.,:

class Something:
    x: int

yields

x: int

To Reproduce Steps to reproduce the behavior:

  1. Create a Python file test.py with contents
class Something:
    x: int
  1. Install packages:
pip install sphinx sphinx-markdown-builder
  1. Build the scaffolding for Sphinx
sphinx-apidoc -o docs . -a --extensions sphinx_markdown_builder --full
  1. Build the documentation
cd docs && make markdown
  1. The Markdown file at docs/_build/markdown/test.md is
# test module

### *class* test.Something

Bases: `object`

#### x*: int*

where the last line renders as

x: int

Expected behavior The last line should instead render as (for instance):

x : int

which can be achieved by having an additional space before the first star:

#### x *: int*

Environment (please complete the following information):

sphinx-autodoc-typehints==1.24.0
sphinx-markdown-builder==0.6.5
sphinxcontrib-applehelp==1.0.7
sphinxcontrib-devhelp==1.0.5
sphinxcontrib-htmlhelp==2.0.4
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.6
sphinxcontrib-serializinghtml==1.1.9
liran-funaro commented 7 months ago

@ttesileanu Thank you for the report. I'm sorry it took so much time to reply. I've been on vacation, followed by a war. I'll attend to this issue in the following weeks.

ttesileanu commented 7 months ago

Thanks! And so sorry for what you're going through... 😞

liran-funaro commented 6 months ago

@ttesileanu I've pushed a fix to the main branch that should fix this issue. I couldn't reproduce the issue with the example you provided, but I managed to find an example to reproduce this issue. I guess this might be because you are not using the latest Sphinx version, or that sphinx-apidoc behaves differently than sphinx-build.

You can install the latest commit and see if it solves this issue for you. If it solves it, I'll upload a new version soon.

pip uninstall sphinx-markdown-builder
pip install git+https://github.com/liran-funaro/sphinx-markdown-builder.git@main
ttesileanu commented 6 months ago

This fixes it, thanks! (And sorry for the delayed reply.)

liran-funaro commented 5 months ago

Great to hear. This fix is now part of the latest release (0.6.6). Please check it out and update here if this works for you.

ttesileanu commented 4 months ago

Yes, v0.6.6 works! Thanks!