search

NiklasRosenstein / pydoc-markdown

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

Adds Support for Nextra Configuration #290

Open ieaves opened 1 year ago

ieaves commented 1 year ago

This PR adds support for the Nextra Docs Theme to pydocs-markdown. The basic site structure is similar to docusaurus so I've reused the docusaurus renderer without the sidebar.json.

Changelog

I've attempted to add a changelog entry in accordance with the contribution-guidelines however, after installing slap-cli with pipx I received an error

slap changelog add -t changelog -d "Adds Nextra support"

> invalid change type: changelog

I eventually realized the issue was with the type flag so I've included updates to the contributing markdown with references to the acceptable set of types and a typo fix.

Slap

I'm going to add these comments here since it looks like you're also the author of Slap but it looks like slaps docs build might have failed pulling in the readme from the project root see here.

ieaves commented 1 year ago

Any chance you have some time to look at this @NiklasRosenstein ?

NiklasRosenstein commented 1 year ago

Hey @ieaves , thanks for the PR! I hope to find some time later this week.

ieaves commented 1 year ago

No worries! Thanks for writing this package!

ieaves commented 1 year ago

Hey @NiklasRosenstein, any updates?

ieaves commented 1 year ago

@NiklasRosenstein one more ping. Totally understand if nextra isn't part of your roadmap. I'm happy to maintain an alternative fork with nextra support if so but as of now it's difficult to add doc builds into our CI without something like this.

NiklasRosenstein commented 8 months ago

Hi @ieaves, I'm finally getting back to this! Sorry for the months long silence.

I've made a few changes from your PR on the nextra branch, including an examples/nextra folder. I'm not familiar with Nextra. Do you happen to know why the pages generated by Pydoc-Markdown in the examples/nextra/docs/pages/school/ folder are shown in the menu but nothing happens when I click on them? This feels like some configuration is missing.

image

ieaves commented 8 months ago

Hey Niklas!

Lovely! Thanks for picking this back up.

It looks like that example repo links out to a generic nextra repository. You might have some uncommitted changed but I think I can answer your question still. This is one of the attributes of Nextra I find annoying but you need an mdx file with the same name as the subdirectory at the same level to make the folder clickable.

So if you have a school folder alone, clicking would expand the folder content on the left hand bar but if you had a school folder AND a school.mdx next to the school folder, it would expand the bar and navigate to the page.

On Sat, Nov 11 2023 at 7:56 AM, Niklas Rosenstein < @.*** > wrote:

Hi @ieaves ( https://github.com/ieaves ) , I'm finally getting back to this! Sorry for the months long silence.

I've made a few changes from your PR on the nextra branch ( https://github.com/NiklasRosenstein/pydoc-markdown/tree/nextra ) , including an examples/nextra folder. I'm not very familiar with Nextra. Do you happen to know why the pages generated by Pydoc-Markdown in the examples/nextra/docs/pages/school/ folder are shown in the menu but nothing happens when I click on them? This feels like some configuration is missing for the example to work.

image ( https://user-images.githubusercontent.com/1318438/282245896-d668685c-c061-4272-85c8-7805df762065.png )

— Reply to this email directly, view it on GitHub ( https://github.com/NiklasRosenstein/pydoc-markdown/pull/290#issuecomment-1806823860 ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AB3MV5ZIZXN4J4TSKVMC7ULYD57XZAVCNFSM6AAAAAAYUQWUJCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQMBWHAZDGOBWGA ). You are receiving this because you were mentioned. Message ID: <NiklasRosenstein/pydoc-markdown/pull/290/c1806823860 @ github. com>