Changes to the HTML theme?

[karimbahgat]

Finally a documentation tool that takes markdown! I was actually just creating a very similar package, but mine was a lot messier and less complete. I hope news of this package keeps spreading, it would be a great revelation to the many Python programmers (esp beginners) who want to spend less time documenting their work and do it in a more intuitive language. Sphinx really can be a pain, and I still have not gotten it to work for me (too much configuration).

I really loved the sleek look of the pdoc theme. However, there were just some minor issues that I think would make it even better. It might be a lot to ask, but if there is easy access and control over the output html tags, and if you agree with my suggestions, this should really just be about changing some of the HTML tags, and adding some new ones.

• When browsing the pdoc pages of my own multilevel package, I noticed that there was no link to help me get "up" on level, or even back to the top/main package page. This way it made me feel like I was stuck on one page at a time, as there was no easy way for me to quickly go back and regain an overview of the package structure or of how far I had progressed into it, short of using the browsers back-button. The "Index" header at the top of the sidepanel could be a link for going back to the top, and a browsing tree showing the relative location within the package might also be useful.
• If there is a module-level docstring with some intro/overview text, add a link to that module docstring in the sidebar index list, as well as sublinks reflecting any markdown headings within that module docstring, This would allow package authors to give their users a gentler intro to each module with more context, philosophy, and usage examples, before jumping into the details. It would also be more conducive to a proper full-length front-page, with links to sections on installations, philosophy, basic usage examples, etc.
• Make the sidebar follow the screen (instead of scrolling along with the content), making it is easier to quickly jump between sections without having to always scroll up to the top first, and thus giving the users a better understanding and overview.
• Of a somewhat personal preference, I would have liked to see the color of the sidebar a bit darker like the gray used on the Py3 site to give it more depth and better differentiate it from the main content. Same goes for the main text headers of the variables, functions, classes, and methods, which could have a darker tint to their gray background, to make them pop out more from the screen.
• On a related note, what are the possibilites for color and other theme styling for the user? Is there any available customization built into pdoc, such as colors, sidepane layout, or turning off the source code buttons, or would we have to go in and change pdoc itself? If there was at least some theme styling, that would give pdoc roughly the same flexible feature-set as Sphinx and still be much easier to use.

Let me know what you think is possible, or point me in the direction of where to start if was to make a pull request. And again, great work!

[mikecharles]

👍

[blbarker]

Was glad to discover pdoc today as I've been contemplating whether I really want to go down the sphinx road again on a new project.

From what I've tried of pdoc so far, lack of multi-level navigation is the only thing holding me back. Would really love to see karimbahgat's first two bullets get in (glad the 3rd bullet is in queue!)