search

mkdocs / mkdocs-click

An MkDocs extension to generate documentation for Click command line applications
https://pypi.org/project/mkdocs-click
Apache License 2.0
109 stars 16 forks source link

Fix module name in markdown extensions block #37

Closed jmaupetit closed 1 year ago

jmaupetit commented 3 years ago

Markdown extensions block should list python module names and not package names.

Thank you for this amazing project :muscle:

florimondmanca commented 3 years ago

@jmaupetit Thanks! Just to clarify, does using mkdocs-click fail, or is it simply not a recommended practice from Python Markdown? Indeed I can see that builtin Markdown extensions use the module_name as the entrypoint: https://python-markdown.github.io/extensions/, just didn't know it was a convention. :)

jmaupetit commented 3 years ago

It fails at it tries to load the mkdocs-click python module.

florimondmanca commented 3 years ago

Interesting, I'm not seeing this in https://github.com/DataDog/integrations-core (we use mkdocs-click there).

I think it works thanks to our Markdown extension entry point definition here:

https://github.com/DataDog/mkdocs-click/blob/a01754d73dbfebdd40907dc4a731f4f1f76e95f0/setup.py#L38

Which seems to be designed to make markdown.Markdown(extensions=["mkdocs-click"]) (using a string) work as expected. I can verify this because if I change this entry_points definition to point to eg mkdocs-click2 = ..., then mkdocs-click isn't recognized anymore by MkDocs. :-)

Are your setuptools, mkdocs-click, mkdocs and markdown versions up to date? Which Python version are you on?

jmaupetit commented 3 years ago

Are your setuptools, mkdocs-click, mkdocs and markdown versions up to date?

Yes, I think so: https://github.com/openfun/ralph/blob/master/setup.cfg#L54-L55

Which Python version are you on?

Python 3.9 https://github.com/openfun/ralph/blob/master/Dockerfile#L2

oprypin commented 1 year ago

Python-Markdown primarily looks at entrypoints, and the entrypoint is correctly defined as mkdocs-click. https://github.com/mkdocs/mkdocs-click/blob/7b094b817d43e7eb22af44ddfb211a05db5533d3/pyproject.toml#L37

Just make sure that the module is properly installed with pip, rather than just dropped into a folder or something like that.

Python-Markdown also has a fallback of trying to import the module directly, and so mkdocs_click would work too, but it shouldn't be the primary advertised method.