sphinx style seems ignored when passed in as option
thatlittleboy opened this issue · comments
Describe the bug
As per title. I specify sphinx
as a docstring_style
option but the handler is rendering as per Google instead of Sphinx. (Ignoring my option specification).
To Reproduce
Steps to reproduce the behavior:
Following usage instructions here: https://mkdocstrings.github.io/python-legacy/usage/#usage
pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python-legacy
. See my pip freeze output at the bottom.- Noting that the documentation mentioned the "accepted
docstring_style
are:google, numpy, sphinx, or None. Default: "google"
". Createmkdocs.yml
:site_name: "sample_proj" watch: - sample_proj theme: name: "material" plugins: - search - mkdocstrings: handlers: python: options: members: - my_function_google - my_function_sphinx docstring_style: sphinx
- Python functions for testing
def my_function_sphinx(param1: int, param2: Optional[str] = None) -> str: """A short description of this function. Complex markup is supported in the main description section. I'm a code block! :param param1: An integer? :param param2: A string? If you have a long description, you can split it on multiple lines. """ return f"{param2}{param1}" def my_function_google(param1: int, param2: Optional[str] = None) -> str: """A short description of this function. Complex markup is supported in the main description section. I'm a code block! Args: param1: An integer? param2: A string? if you have a long description, you can split it on multiple line """ return f"{param2}{param1}"
mkdocs serve
.- The function with Google docstring style is rendered correctly and sphinx not, despite me specifying
sphinx
in the options. I tried changingsphinx
->restructured-text
inmkdocs.yml
and same problem.
Expected behavior
Param table for sphinx
style to be rendered normally.
Screenshots
Note that the docs itself is also rendered wrongly, it seems. https://mkdocstrings.github.io/python-legacy/usage/#annotations_1
System (please complete the following information):
mkdocstrings-python (legacy)
version: 0.2.3- Python version: 3.9
- OS: MacOS
Additional context
Add any other context about the problem here.
pip freeze
certifi==2022.12.7 charset-normalizer==3.0.1 click==8.1.3 colorama==0.4.6 ghp-import==2.1.0 idna==3.4 Jinja2==3.1.2 Markdown==3.3.7 MarkupSafe==2.1.2 mergedeep==1.3.4 mkdocs==1.4.2 mkdocs-autorefs==0.4.1 mkdocs-material==9.0.6 mkdocs-material-extensions==1.1.1 mkdocstrings==0.20.0 mkdocstrings-python-legacy==0.2.3 packaging==23.0 Pygments==2.14.0 pymdown-extensions==9.9.2 python-dateutil==2.8.2 pytkdocs==0.16.1 PyYAML==6.0 pyyaml_env_tag==0.1 regex==2022.10.31 requests==2.28.2 six==1.16.0 urllib3==1.26.14 watchdog==2.2.1
I debugged it a little, I think the main issue is here (?)
python-legacy/src/mkdocstrings_handlers/python/handler.py
Lines 253 to 257 in 9c5c653
So I think the problem is two-fold:
python-legacy
is not passingdocstring_style
(anddocstring_options
) topytkdocs
, which is why it is parsing google by default.pytkdocs
is still expecting "restructured-text" (not "sphinx"); We could either do a mapping inpython-legacy
internals so that if users pass in "sphinx" in the options, we pass "restructured-text" to pytkdocs, or we make pytkdocsPARSERS
accept sphinx.
Hello, thanks for the detailed report!
Sorry, the docs are definitely wrong, they should say restructured-text
and not sphinx
in the legacy handler.
I'll check your theory, it's possible that the option is not correctly passed to pytkdocs indeed.