Feature suggestion: Getting index.html contents from a markdown file

[wq2012]

Expected Behavior

Well, it's not something important, but a nice-to-have feature.

Currently the <article> part of index.html comes of the docstring of __init__.py. However, some authors prefer to leave the details of the package/module in a markdown file like README.md, for easier access to the audience, instead of __init__.py.

It might be a nice feature if pdoc has an argument that supports converting a markdown file to HTML and injecting the converted HTML part into the <article> part of index.html.

Actual Behavior

N/A

Steps to Reproduce

N/A

Additional info

• pdoc version:
  0.5.1

[b52]

+1

[kernc]

Which README.md would that be, the one in the same directory as __init__.py or one upper?

Only README.md or also readme.md, README.txt, README.rst?

[kernc]

The way it would yield the most is with reST .. include:: directive.

How do you feel about that?

[kernc]

If anyone would have a stab at that, the code is here.
There's already an exception for .. image:: and .. figure::.

pdoc/pdoc/html_helpers.py

Lines 189 to 215 in e2739ce

	def _admonition(match):
	indent, type, value, text = match.groups()
	if type in ('image', 'figure'):
	return '{}\n'.format(
	indent, text.translate(str.maketrans({'\n': ' ',
	'[': '\\[',
	']': '\\]'})).strip(), value)
	if type == 'versionchanged':
	title = 'Changed in version: ' + value
	elif type == 'versionadded':
	title = 'Added in version: ' + value
	elif type == 'deprecated' and value:
	title = 'Deprecated since version: ' + value
	elif type == 'admonition':
	title = value
	elif type.lower() == 'todo':
	title = 'TODO'
	text = value + ' ' + text
	else:
	title = type.capitalize()
	if value:
	title += ': ' + value
	text = '\n'.join(indent + ' ' + line
	for line in inspect.cleandoc(text).split('\n'))
	return '{}!!! {} "{}"\n{}\n'.format(indent, type, title, text)

[wq2012]

From the user's perspective, I was thinking of using it like:

pdoc mymodule --html --inject-markdown-to-index=/PATH/TO/MY/README.md

[kernc]

I think that's too ambiguous. Every package with __init__.py has an index. Which index?

Then, you can't control whether the injection is appended to or replaces the existing docstring.

Do you particularly dislike the .. include:: approach?

[b52]

I'm in favor of the .. include:: approach. Seems easy enough while allowing a lot more flexibility.

On a different page, what is rendered as index when I make pdoc build multiple modules?

[wq2012]

.. include:: is definitely good! Flexibility is great.

I was just mentioning an alternative user interface in my previous comment.

[kernc]

On a different page, what is rendered as index when I make pdoc build multiple modules?

Each disjunct package produces its own directory. There is no index.html to bind them.

[b52]

@kernc If you give me some pointers I'll happily write up a PR.

[kernc]

• Make another admonition type exception for 'include' (probably call another function if more than a couple of lines).
  • Open up a file, read and return its contents but with each line preceded by indent.
    • If the file doesn't exist, re-raise a more descriptive exception.
  • Relative paths should probably be relative to the include statement appearance. You will need to pass module to _ToMarkdown.admonitions() to be able to handle relative includes.
  • I don't think you need to worry about directive options (:start-line:, :end-line:, ...) that you would find in text. Unless you find them trivial to implement, I'm completely happy if we don't support them or maybe add them later on an as-needed basis.
• Add a documentation subsection "Supported reST directives", describing in brief what directives are supported and how.

[b52]

I wrote up everything as described (including the start end stuff) in PR #16 .