Improve documentation with direct use of MkDocs (#398)

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

MANIFEST.in

@@ -1,6 +1,7 @@
 include LICENSE *.md *.yml *.toml
 
 include tox.ini
+recursive-include docs *.md
 recursive-include tests *.py
 
 include .bumpversion.cfg

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/reference.md

@@ -0,0 +1,3 @@
+# Reference
+
+::: dotenv

mkdocs.yml

@@ -0,0 +1,23 @@
+site_name: python-dotenv
+repo_url: https://github.com/theskumar/python-dotenv
+edit_uri: ""
+theme:
+  name: material
+  palette:
+    primary: green
+markdown_extensions:
+  - mdx_truly_sane_lists
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          rendering:
+            show_root_heading: yes
+            show_submodules: no
+            separate_signature: yes
+  - search
+nav:
+  - Home: index.md
+  - Changelog: changelog.md
+  - Contributing: contributing.md
+  - Reference: reference.md

requirements.txt

@@ -1,11 +1,16 @@
+black~=22.3.0
 bumpversion
 click
 flake8>=2.2.3
 ipython
+mdx_truly_sane_lists~=1.2
+mkdocs-include-markdown-plugin~=3.3.0
+mkdocs-material~=8.2.9
+mkdocstrings[python]~=0.18.1
+mkdocs~=1.3.0
 pytest-cov
 pytest>=3.9
 sh>=1.09
 tox
-wheel
 twine
-portray
+wheel

src/dotenv/main.py

@@ -198,10 +198,10 @@ def unset_key(
     encoding: Optional[str] = "utf-8",
 ) -> Tuple[Optional[bool], str]:
     """
-    Removes a given key from the given .env
+    Removes a given key from the given `.env` file.
 
-    If the .env path given doesn't exist, fails
-    If the given key doesn't exist in the .env, fails
+    If the .env path given doesn't exist, fails.
+    If the given key doesn't exist in the .env, fails.
     """
     if not os.path.exists(dotenv_path):
         logger.warning("Can't delete from %s - it doesn't exist.", dotenv_path)
@@ -316,16 +316,17 @@ def load_dotenv(
 ) -> bool:
     """Parse a .env file and then load all the variables found as environment variables.
 
-    - *dotenv_path*: absolute or relative path to .env file.
-    - *stream*: Text stream (such as `io.StringIO`) with .env content, used if
-      `dotenv_path` is `None`.
-    - *verbose*: whether to output a warning the .env file is missing. Defaults to
-      `False`.
-    - *override*: whether to override the system environment variables with the variables
-      in `.env` file.  Defaults to `False`.
-    - *encoding*: encoding to be used to read the file.
+    Parameters:
+        dotenv_path: Absolute or relative path to .env file.
+        stream: Text stream (such as `io.StringIO`) with .env content, used if
+            `dotenv_path` is `None`.
+        verbose: Whether to output a warning the .env file is missing.
+        override: Whether to override the system environment variables with the variables
+            from the `.env` file.
+        encoding: Encoding to be used to read the file.
 
-    If both `dotenv_path` and `stream`, `find_dotenv()` is used to find the .env file.
+    If both `dotenv_path` and `stream` are `None`, `find_dotenv()` is used to find the
+    .env file.
     """
     if dotenv_path is None and stream is None:
         dotenv_path = find_dotenv()
@@ -356,12 +357,10 @@ def dotenv_values(
     `{"foo": None}`
 
     Parameters:
-
-    - `dotenv_path`: absolute or relative path to the .env file.
-    - `stream`: `StringIO` object with .env content, used if `dotenv_path` is `None`.
-    - `verbose`: whether to output a warning if the .env file is missing. Defaults to
-      `False`.
-    - `encoding`: encoding to be used to read the file. Defaults to `"utf-8"`.
+        dotenv_path: Absolute or relative path to the .env file.
+        stream: `StringIO` object with .env content, used if `dotenv_path` is `None`.
+        verbose: Whether to output a warning if the .env file is missing.
+        encoding: Encoding to be used to read the file.
 
     If both `dotenv_path` and `stream` are `None`, `find_dotenv()` is used to find the
     .env file.