search

NiklasRosenstein / pydoc-markdown

Create Python API documentation in Markdown format.
http://niklasrosenstein.github.io/pydoc-markdown/
Other
453 stars 102 forks source link

Add option to Render the heading#1 for letting readthedocs to generate TOC automatically #214

Closed t6847kimo closed 2 years ago

t6847kimo commented 2 years ago

Is your feature request related to a problem? Please describe.

Hi, I have noticed that the readthedocs will generate TOC by default and it's beautiful enough, so I don't need to set render_toc as true. But, currently, the heading#1 is reserved only for title of TOC, so when render_toc is false, the TOC will also be removed in readthedocs.

I have tried to set render_toc to false and set render_toc_title, but the heading is still not presented.

Describe the solution you'd like

So I want to have an option to assign the #1heading in the beginning of markdown file.

Describe alternatives you've considered

Or, just render the "API Document" by default when render_toc is false, it's also OK for me.

Additional context

By the way, I can help to contribute this feature as long as you help to indicate the location of modification. Thank you very much!

NiklasRosenstein commented 2 years ago

Hey @t6847kimo! I would be happy to review a PR for this :)

The TOC is rendered here:

https://github.com/NiklasRosenstein/pydoc-markdown/blob/a0f53887d02c76c73a195c074f7f844baf5689a8/src/pydoc_markdown/contrib/renderers/markdown.py#L213-L223

But if you want to render the page name into the Markdown file before anything else, you probably should look into the MkDocs renderer instead because the MarkdownRenderer does not have an understanding of the page's title. MkDocs invokes the MarkdownRenderer here:

https://github.com/NiklasRosenstein/pydoc-markdown/blob/a0f53887d02c76c73a195c074f7f844baf5689a8/src/pydoc_markdown/contrib/renderers/mkdocs.py#L164-L166

And the page's render method is here:

https://github.com/NiklasRosenstein/pydoc-markdown/blob/a0f53887d02c76c73a195c074f7f844baf5689a8/src/pydoc_markdown/util/pages.py#L153-L173

There's many was this could be done. I think I would prefer an option in the Mkdocs renderer like render_page_title and that option is either passed to Page.render() or is set as an option in the Markdown renderer along with the title string.

Thanks!

t6847kimo commented 2 years ago

Hi, #216 has already submitted, please take a look. Thank you very much!