Improve documentation with direct use of MkDocs

[bbc2]

Improvements:

• Only the public API is documented
  • Thanks to mkdocstrings with show_submodules: no.
• Function parameter documentation is parsed and shown in tables.
• None paragraphs are removed.
  • This was reported at fix #22 remove "None" from markdown output timothycrosley/pdocs#25 but hasn't been merged.
• Footer layout is fixed.
  • It's currently broken with Portray, even on their own documentation (https://timothycrosley.github.io/portray/).
• Fix list levels in table of contents on home page.
  • Thanks to mdx_truly_sane_lists.
• Remove broken "edit" links.

Portray is great but I think we can do better by directly using MkDocs.

The new way to deploy the documentation is:

mkdocs gh-deploy

The result can currently temporarily be seen at https://bbc2.github.io/python-dotenv/.

[theskumar]

Portray is great but I think we can do better by directly using MkDocs.

Portray was meant to be easy to use and low maintenance. It seems it is not well maintained and introducing unwanted bottlenecks, also the project now needs more comprehensive docs, let's move forward with mkdocs.

While I think the current PR can be merged as-is. I would like to use the opportunity to document more improvements that this project can benefit from. We can address them as these as we go:

1. Simplify the README so it consists of the summary and overview only. Detailed docs are then available via rendered mkdocs. The README is already getting too big now.
2. Use github-actions to publish the docs from master branch.
3. Add a developer guide or enhance the CONTRIBUTING.md to include the working with docs section.
4. If possible get rid of symlinking the docs (Portray was primarily used for that reason).