Update documentation

AUTHORS.rst

@@ -13,7 +13,7 @@ The existence of ``django-environ`` would have been impossible without these
 projects:
 
 - `rconradharris/envparse <https://github.com/rconradharris/envparse>`_
-- `jacobian/dj-database-url <https://github.com/jacobian/dj-database-url>`_
+- `jazzband/dj-database-url <https://github.com/jazzband/dj-database-url>`_
 - `migonzalvar/dj-email-url <https://github.com/migonzalvar/dj-email-url>`_
 - `ghickman/django-cache-url <https://github.com/ghickman/django-cache-url>`_
 - `dstufft/dj-search-url <https://github.com/dstufft/dj-search-url>`_

README.rst

@@ -104,8 +104,8 @@ article.
 
 Using ``django-environ`` you can stop to make a lot of unversioned
 ``settings_*.py`` to configure your app.
-See `cookiecutter-django <https://github.com/pydanny/cookiecutter-django>`_ for
-a concrete example on using with a django project.
+See `cookiecutter-django <https://github.com/cookiecutter/cookiecutter-django>`_
+for a concrete example on using with a django project.
 
 **Feature Support**
 

docs/Makefile

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view

docs/api.rst

@@ -0,0 +1,45 @@
+=============
+API Reference
+=============
+
+.. currentmodule:: environ
+
+
+The ``__init__`` module
+=======================
+
+.. automodule:: environ
+    :members:
+    :no-undoc-members:
+
+
+The ``compat`` module
+======================
+
+.. automodule:: environ.compat
+    :members:
+    :no-undoc-members:
+
+
+The ``environ`` module
+======================
+
+.. autoclass:: environ.Env
+    :members:
+    :no-undoc-members:
+
+.. autoclass:: environ.FileAwareEnv
+    :members:
+    :no-undoc-members:
+
+.. autoclass:: environ.Path
+    :members:
+    :no-undoc-members:
+
+
+The ``fileaware_mapping`` module
+================================
+
+.. autoclass:: environ.fileaware_mapping.FileAwareMapping
+    :members:
+    :no-undoc-members:

docs/conf.py

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view
@@ -12,9 +12,14 @@
 
 import codecs
 import os
+import sys
 import re
 
 
+PROJECT_DIR = os.path.abspath('..')
+sys.path.insert(0, PROJECT_DIR)
+
+
 def read_file(filepath):
     """Read content from a UTF-8 encoded text file."""
     with codecs.open(filepath, 'rb', 'utf-8') as file_handle:
@@ -23,9 +28,7 @@ def read_file(filepath):
 
 def find_version(meta_file):
     """Extract ``__version__`` from meta_file."""
-    here = os.path.abspath(os.path.dirname(__file__))
-    contents = read_file(os.path.join(here, meta_file))
-
+    contents = read_file(os.path.join(PROJECT_DIR, meta_file))
     meta_match = re.search(
         r"^__version__\s+=\s+['\"]([^'\"]*)['\"]",
         contents,
@@ -56,6 +59,7 @@ def find_version(meta_file):
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
     "notfound.extension",
 ]
 
@@ -75,7 +79,7 @@ def find_version(meta_file):
 
 # The version info
 # The short X.Y version.
-release = find_version('../environ/__init__.py')
+release = find_version('environ/__init__.py')
 version = release.rsplit(u".", 1)[0]
 # The full version, including alpha/beta/rc tags.
 
@@ -85,11 +89,33 @@ def find_version(meta_file):
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-default_role = "any"
+# default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
+#
+# -- Options for linkcheck ----------------------------------------------------
+#
+
+linkcheck_ignore = [
+    # We run into GitHub's rate limits.
+    r"https://github.com/.*/(issues|pull)/\d+",
+]
+
+#
+# -- Options for nitpick ----------------------------------------------------
+#
+
+nitpicky = True
+
+# In nitpick mode (-n), still ignore any of the following "broken" references
+# to non-types.
+nitpick_ignore = [
+    ('py:class', 'file'),
+    ('py:class', 'urlparse.ParseResult'),
+]
+
 #
 # -- Options for extlinks ----------------------------------------------------
 #

docs/deprecations.rst

@@ -0,0 +1,12 @@
+============
+Deprecations
+============
+
+Features deprecated in 0.9.0
+============================
+
+Methods
+-------
+
+* The :meth:`.environ.Env.unicode` method is deprecated as it was used
+  for Python 2.x only. Use :meth:`.environ.Env.str` instead.

docs/docutils.conf

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view

docs/getting-started.rst

@@ -10,7 +10,7 @@ Requirements
 ------------
 
 * `Django <https://www.djangoproject.com/>`_ >= 1.11
-* `Python <https://www.python.org/>`_ >= 3.4
+* `Python <https://www.python.org/>`_ >= 3.5
 
 Installing django-environ
 _________________________
@@ -52,7 +52,7 @@ it to your system.
 More information about ``pip`` and PyPI can be found here:
 
 * `Install pip <https://pip.pypa.io/en/latest/installing/>`_
-* `Python Packaging User Guide <https://packaging.python.org/>`_
+* `Python Packaging User Guide <https://packaging.python.org/en/latest/>`_
 
 Usage
 =====
@@ -112,7 +112,7 @@ FAQ
 #. **Can django-environ determine the location of .env file automatically?**
 
    ``django-environ`` will try to get and read ``.env`` file from the project
-   root if you haven't specified the path for it when call ``read_env``.
+   root if you haven't specified the path for it when call :meth:`.environ.Env.read_env`.
    However, this is not the recommended way. When it is possible always specify
    the path tho ``.env`` file. Alternatively, you can use a trick with a
    environment variable pointing to the actual location of .env file.

docs/index.rst

@@ -1,3 +1,5 @@
+.. module:: environ
+
 =======================================
 Welcome to django-environ documentation
 =======================================
@@ -38,6 +40,7 @@ Full Table of Contents
    tips
    contributing
    backers
+   api
 
 .. include:: ../README.rst
    :start-after: -project-information-
@@ -47,4 +50,5 @@ Full Table of Contents
    :maxdepth: 1
 
    license
+   deprecations
    changelog

docs/tips.rst

@@ -10,7 +10,7 @@ Docker (swarm) and Kubernetes are two widely used platforms that store their
 secrets in tmpfs inside containers as individual files, providing a secure way
 to be able to share configuration data between containers.
 
-Use ``environ.FileAwareEnv`` rather than ``environ.Env`` to first look for
+Use :class:`.environ.FileAwareEnv` rather than :class:`.environ.Env` to first look for
 environment variables with ``_FILE`` appended. If found, their contents will be
 read from the file system and used instead.
 
@@ -42,8 +42,8 @@ the example ``docker-compose.yml`` for would contain:
 Using unsafe characters in URLs
 ===============================
 
-In order to use unsafe characters you have to encode with ``urllib.parse.quote`` before you set into ``.env`` file.
-Encode only the value (i.e. the password) not the whole url.
+In order to use unsafe characters you have to encode with :py:func:`urllib.parse.quote`
+before you set into ``.env`` file. Encode only the value (i.e. the password) not the whole url.
 
 .. code-block:: shell
 
@@ -292,7 +292,8 @@ while ``./manage.py runserver`` uses ``.env``.
 Using Path objects when reading env
 -----------------------------------
 
-It is possible to use of ``pathlib.Path`` objects when reading environment file from the filesystem:
+It is possible to use of :py:class:`pathlib.Path` objects when reading environment
+file from the filesystem:
 
 .. code-block:: python
 
@@ -319,7 +320,7 @@ Overwriting existing environment values from env files
 
 If you want variables set within your env files to take higher precedence than
 an existing set environment variable, use the ``overwrite=True`` argument of
-``read_env``. For example:
+:meth:`.environ.Env.read_env`. For example:
 
 .. code-block:: python
 

environ/__init__.py

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view
@@ -23,9 +23,9 @@
     __url__
     __description__
 
-Refer to the `documentation <https://django-environ.readthedocs.org/>`_
+Refer to the `documentation <https://django-environ.readthedocs.io/en/latest/>`_
 for details on the use of this package.
-"""
+"""  # noqa: E501
 
 from .environ import *
 

environ/compat.py

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view
@@ -39,8 +39,8 @@ class ImproperlyConfigured(Exception):
     REDIS_DRIVER = 'django_redis.cache.RedisCache'
 
 
-# back compatibility for pymemcache
 def choose_pymemcache_driver():
+    """Backward compatibility for pymemcache."""
     old_django = DJANGO_VERSION is not None and DJANGO_VERSION < (3, 2)
     if old_django or not find_loader('pymemcache'):
         # The original backend choice for the 'pymemcache' scheme is

environ/environ.py

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view

environ/fileaware_mapping.py

@@ -1,6 +1,6 @@
 # This file is part of the django-environ.
 #
-# Copyright (c) 2021, Serghei Iakovlev <[email protected]>
+# Copyright (c) 2021-2022, Serghei Iakovlev <[email protected]>
 # Copyright (c) 2013-2021, Daniele Faraglia <[email protected]>
 #
 # For the full copyright and license information, please view
@@ -14,14 +14,14 @@
 
 class FileAwareMapping(MutableMapping):
     """
-    A mapping that wraps os.environ, first checking for the existance of a key
+    A mapping that wraps os.environ, first checking for the existence of a key
     appended with ``_FILE`` whenever reading a value. If a matching file key is
     found then the value is instead read from the file system at this location.
 
     By default, values read from the file system are cached so future lookups
     do not hit the disk again.
 
-    A ``_FILE`` key has higher precidence than a value is set directly in the
+    A ``_FILE`` key has higher precedence than a value is set directly in the
     environment, and an exception is raised if the file can not be found.
     """