Create an introduction page?

[allefeld]

In addition to the module-documentation pages generated by the pdoc command-line utility, I would like to create an introduction page for the distribution package as a whole (as opposed to the import packages / modules), which describes the different modules in context.

pdoc has no option to do, and I've seen the issues where corresponding requests have been denied by the author. I therefore intend to do so myself, using the programmatic API of the pdoc module. Unfortunately, I cannot quite figure out how to do it.

The idea would be to

• have a Markdown text for the page, e.g. read from a file
• create an HTML document in the same style as the pdoc-generated pages, i.e. optimally using the same templates.

It would be great if you could give me some pointers!

[allefeld]

Or, would you be willing to share how you created pdoc3.github.io using pdoc?

[kernc]

Why not just look at the source. :grin: The premise idea is to have the toplevel mypackage/__init__.py contain the main introductory content / usage examples: https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/init.py#L1-L9 This is as far as same pdoc styling and same templates go. However, if you mean the homepage, it's a complete separate, manually written/committed index.html, linking to generated documentation: https://github.com/pdoc3/pdoc/blob/5d4ab10ba90a8f0ca629c4349818a7bb0a21af0e/index.html#L241

[kernc]

I would like to create an introduction page for the distribution package as a whole, which describes the different modules in context. pdoc has no option to do, and I've seen the issues where corresponding requests have been denied by the author.

If you mean issue https://github.com/pdoc3/pdoc/issues/101, it's still open for taking on. :+1:

[allefeld]

Yes, I had looked at the code, and at the moment do it the same way for my project tikz.

I meant the homepage, and had assumed it was generated from a template as well. Right now I have a disconnect where the package description is essentially the repository README, as opposed to the pdoc-generated module description: https://github.com/allefeld/pytikz vs https://allefeld.github.io/pytikz/tikz/.

Yes, what I thought about doing is similar to what #101 describes. However, the package page layout would be similar to the module pages, with a sidebar on the left listing the local TOC and the modules, and the content on the right coming from an extra md file.

I did first steps taking that on, but what I couldn't figure out is how to convert that extra md file to HTML using pdocs API (which would allow automatic links to modules/classes/etc.). As far as I can see, the Markdown-processing parts of pdoc are strongly tied to processing modules. That's what I would appreciate pointers on.

[kernc]

As far as I can see, the Markdown-processing parts of pdoc are strongly tied to processing modules

Yeah, as this is an API docs generator and docs hierarchy following module hierarchy is a selling point, it appears they are. But module reference is only used to lookup the ref'd objects in the module's context: https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/html_helpers.py#L465-L470 https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/html_helpers.py#L506 https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/init.py#L839-L841 which for CLI operations is a shared global one: https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/init.py#L69-L84 https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/init.py#L580

If you can find a way to hook into that, welcome.