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 15 forks source link

Does not generate toc entries (e.g. that are compatible with mkdocs-material) #27

Closed frankier closed 3 years ago

frankier commented 3 years ago

mkdocs-click doesn't seem to generate toc entries that can be used by mkdocs-material. This means that themes that use this information like mkdocs-material doesn't show the entries, which is a bit of a drawback for big/nested commands:

Compare mkdocstrings:

https://frankier.github.io/skelshop/io/

mkdocs-click:

https://frankier.github.io/skelshop/cli/

Is this where mkdocstrings does it? https://github.com/pawamoy/mkdocstrings/blob/6453026fac287387090a67cce70c078377d107dd/src/mkdocstrings/plugin.py#L172

I suppose that again it's not possible with only a markdown extension, but a full mkdocs extension is needed.

florimondmanca commented 3 years ago

@frankier Hello!

I think you might have to set :depth: 1. By default that's 0, so means headers are generated started from <h1>, which means some themes might not display them properly in the sidebar. If you look at the example/ docs in this repo you'll see we set :depth: 1 as well, basically for this reason (for the ReadTheDocs theme).

Let me know if that helps; maybe there's a note we could add to the docs about this.

frankier commented 3 years ago

Yep that works. Thanks! Submitted a doc PR.