move main docstring into a file

[cs01]

This makes the code easier to read since it's not underneath a large docstring. It also makes the documentation easier to edit since text editors can add syntax highlighting to the raw markdown content, and do realtime markdown previews.

[cs01]

I want to run the markdown autoformatter on this file to make it more consistent, but I can't tell what format its contents are. Is it markdown? Markdown with some pdoc syntax mixed in? Rst?

[kernc]

I'm sorry for not having been more verbose up front. Let's just do the moving in this PR (which will become a commit) and the TBD reflowing in a subsequent PR. I'm sure you can see the advantage of this (large, strictly moving remaining a stand-alone commit).

[kernc]

make it more consistent

What do you mean? 😕

It's actually simple Markdown Extra. Really just what is supported by Python Markdown with enabled plugins.

pdoc/pdoc/html_helpers.py

Lines 67 to 77 in eda27f3

	extensions=[
	"markdown.extensions.abbr",
	"markdown.extensions.attr_list",
	"markdown.extensions.def_list",
	"markdown.extensions.fenced_code",
	"markdown.extensions.footnotes",
	"markdown.extensions.tables",
	"markdown.extensions.admonition",
	"markdown.extensions.smarty",
	"markdown.extensions.toc",
	],

[kernc]

It's actually simple Markdown Extra.

And some reST directives, which are in the pipeline transformed into markdown admonitions.

[kernc]

Btw, thanks for this! Indeed, both files are much more manageable now! 😄 🚀

[cs01]

Ah sorry about that "revert typo" commit. What happened there was I am using VS Code and they have an auto-formatter for markdown files which I forgot I ran.

I was asking earlier about the language of the docstring, because when I ran the VS Code autoformatter it was stripping away what looked like useful information. I see now that is because pdoc is using various syntax that the autoformatter doesn't recognize.

make it more consistent

What do you mean?

Consistent heading syntax, for example. i.e. ## next to title vs ------ underneath the title. Also various capitalization, etc. See the changes in this diff.

 Where does `pdoc` get documentation from?	
-----------------------------------------

is transformed to

## Where does `pdoc` get documentation from?

[kernc]

This PR introduced a bug with sidebar TOC no longer rendering when the docstring was included from another file. @cs01 Looking at your website actually made me aware of it. 😄 It's been fixed in 54fc6d0, and the whole lot released moments ago as v0.6.0. Thanks again!

[cs01]

Nice, thanks for the release!