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. 😁
The premise idea is to have the toplevel mypackage/__init__.py contain the main introductory content / usage examples:

pdoc/pdoc/__init__.py

Lines 1 to 9 in 04960e4

	"""
	Python package `pdoc` provides types, functions, and a command-line
	interface for accessing public documentation of Python modules, and
	for presenting it in a user-friendly, industry-standard open format.
	It is best suited for small- to medium-sized projects with tidy,
	hierarchical APIs.
	.. include:: ./documentation.md
	"""

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:

pdoc/index.html

Line 241 in 5d4ab10

<a class="button is-large is-link" title="pdoc documentation" href="doc/pdoc/"

[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 #101, it's still open for taking on. 👍

[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:

pdoc/pdoc/html_helpers.py

Lines 465 to 470 in 04960e4

	if module and link:
	# Hyperlink markdown code spans not within markdown hyperlinks.
	# E.g. `code` yes, but not [`code`](...). RE adapted from:
	# https://github.com/Python-Markdown/markdown/blob/ada40c66/markdown/inlinepatterns.py#L106
	# Also avoid linking triple-backticked arg names in deflists.
	linkify = partial(_linkify, link=link, module=module, wrap_code=True)

pdoc/pdoc/html_helpers.py

Line 506 in 04960e4

dobj = module.find_ident(refname)

pdoc/pdoc/__init__.py

Lines 839 to 841 in 04960e4

	return (self.doc.get(_name) or
	self._context.get(_name) or
	self._context.get(self.name + '.' + _name) or

which for CLI operations is a shared global one:

pdoc/pdoc/__init__.py

Lines 69 to 84 in 04960e4

	class Context(dict):
	"""
	The context object that maps all documented identifiers
	(`pdoc.Doc.refname`) to their respective `pdoc.Doc` objects.
	You can pass an instance of `pdoc.Context` to `pdoc.Module` constructor.
	All `pdoc.Module` objects that share the same `pdoc.Context` will see
	(and be able to link in HTML to) each other's identifiers.
	If you don't pass your own `Context` instance to `Module` constructor,
	a global context object will be used.
	"""
	__pdoc__['Context.__init__'] = False
	_global_context = Context()

pdoc/pdoc/__init__.py

Line 580 in 04960e4

self._context = _global_context if context is None else context

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