add custom homepage intro

[cs01]

It would be nice if the homepage allowed some more context to be written. For example, passing the path to an arbitrary markdown file, such as the README.md, or any other arbitrary content.

Example call:

pdoc --index README.md --html mypackage

[kernc]

Besides module-level docstrings rendering before the API reference, we support .. include:: reST directive.

I.e., in your main module:

"""
Some introductory text ...

.. include:: ../README.md
"""
...

[cs01]

Thanks that definitely helps. I have some html in my markdown and it looks like it has some trouble formatting it. Any tips?

This is what it seems to have trouble with in the README.md:

<h1 align="center">
pygdbmi - Get Structured Output from GDB's Machine Interface
</h1>

<p align="center">
<a href="https://travis-ci.org/cs01/pygdbmi">
<img src="https://travis-ci.org/cs01/pygdbmi.svg?branch=master" />
</a>

<a href="https://pypi.org/project/pygdbmi/">
<img src="https://img.shields.io/badge/pypi-v0.9.0.1-blue.svg"/>
</a>

<img src="https://img.shields.io/badge/python-2.7,3.4,3.5,3.6,pypy-blue.svg"/>
<a href="https://github.com/ambv/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black" /></a>
</p>

[kernc]

Should be fixed in master. 😳 Thanks!

[cs01]

Thanks! That is definitely better. There is still some abnormal formatting though.

This is generated

From this markdown source code

**Documentation**: https://cs01.github.io/pygdbmi/
**Source Code**: https://github.com/cs01/pygdbmi

[kernc]

Should be fixed in master. Thanks again! And keep them coming! 😆

[cs01]

Nice, thanks for all the quick responses 👍 .