Restructure project documentation

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -44,7 +44,7 @@ def find_version(meta_file):
 
 # General information about the project.
 project = 'django-environ'
-copyright = '2021, Daniele Faraglia and other contributors'
+copyright = '2013-2021, Daniele Faraglia and other contributors'
 author = u"Daniele Faraglia"
 
 #

docs/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst

docs/getting-started.rst

@@ -0,0 +1,76 @@
+===============
+Getting Started
+===============
+
+Installation
+============
+
+
+Requirements
+------------
+
+* `Django <https://www.djangoproject.com/>`_ >= 1.11
+* `Python <https://www.python.org/>`_ >= 3.4
+
+Installing django-environ
+_________________________
+
+``django-environ`` is a Python-only package `hosted on PyPI <https://pypi.org/project/django-environ/>`_.
+The recommended installation method is `pip <https://pip.pypa.io/en/stable/>`_-installing into a virtualenv:
+
+.. code-block:: shell
+
+   $ python -m pip install django-environ
+
+.. note::
+
+   After installing ``django-environ``, no need to add it to ``INSTALLED_APPS``.
+
+Then create a ``.env`` file. The file format can be understood from the example below:
+
+.. code-block:: shell
+
+   DEBUG=on
+   SECRET_KEY=your-secret-key
+   DATABASE_URL=psql://user:[email protected]:8458/database
+   SQLITE_URL=sqlite:///my-local-sqlite.db
+   CACHE_URL=memcache://127.0.0.1:11211,127.0.0.1:11212,127.0.0.1:11213
+   REDIS_URL=rediscache://127.0.0.1:6379/1?client_class=django_redis.client.DefaultClient&password=ungithubbed-secret
+
+And use it with ``settings.py`` as follows:
+
+.. include:: ../README.rst
+   :start-after: -code-begin-
+   :end-before: -overview-
+
+.. warning::
+
+   Don't forget to add ``.env`` in your ``.gitignore``. You can also add
+   ``.env.dist`` with a template of your variables to the project repo.
+
+Unstable version
+________________
+
+The master of all the material is the Git repository at https://github.com/joke2k/django-environ.
+So, can also install the latest unreleased development version directly from the ``develop`` branch on
+GitHub. It is a work-in-progress of a future stable release so the experience might be not as smooth.:
+
+.. code-block:: shell
+
+   $ pip install -e git://github.com/joke2k/django-environ.git#egg=django-environ
+   # OR
+   $ pip install --upgrade https://github.com/joke2k/django-environ.git/archive/develop.tar.gz
+
+This command will download the latest version of ``django-environ`` from the
+`Python Package Index <https://pypi.org/project/django-environ/>`_ and install it to your system.
+
+.. note::
+
+   The ``develop`` branch will always contain the latest unstable version, so the experience
+   might be not as smooth. If you wish to check older versions or formal, tagged release,
+   please switch to the relevant `tag <https://github.com/joke2k/django-environ/tags>`_.
+
+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/>`_

docs/index.rst

@@ -1,64 +1,49 @@
-Welcome to Django-environ's documentation!
-==========================================
+=======================================
+Welcome to django-environ documentation
+=======================================
 
-.. automodule:: environ.environ
+Release v\ |release| (`What's new? <changelog>`).
 
 .. include:: ../README.rst
+   :start-after: -teaser-begin-
+   :end-before: -teaser-end-
 
-environ.Env
-===========
-
-..  autoclass:: environ.environ.Env
+Overview
+========
 
-    ..  autoattribute:: BOOLEAN_TRUE_STRINGS
-    ..  autoattribute:: DB_SCHEMES
-    ..  autoattribute:: DEFAULT_DATABASE_ENV
-    ..  autoattribute:: CACHE_SCHEMES
-    ..  autoattribute:: DEFAULT_CACHE_ENV
-    ..  autoattribute:: EMAIL_SCHEMES
-    ..  autoattribute:: DEFAULT_EMAIL_ENV
-    ..  autoattribute:: SEARCH_SCHEMES
-    ..  autoattribute:: DEFAULT_SEARCH_ENV
+.. include:: ../README.rst
+   :start-after: -overview-
+   :end-before: -project-information-
 
-    ..  automethod:: __call__
-    ..  automethod:: str
-    ..  automethod:: bool
-    ..  automethod:: int
-    ..  automethod:: float
-    ..  automethod:: json
-    ..  automethod:: list
-    ..  automethod:: dict
-    ..  automethod:: url
-    ..  automethod:: db_url
-    ..  automethod:: cache_url
-    ..  automethod:: email_url
-    ..  automethod:: search_url
-    ..  automethod:: path
+Quick Start
+===========
 
-    ..  automethod:: read_env
-    ..  automethod:: db_url_config
-    ..  automethod:: cache_url_config
-    ..  automethod:: email_url_config
-    ..  automethod:: search_url_config
-    ..  automethod:: get_value
-    ..  automethod:: parse_value
+.. include:: ../README.rst
+   :start-after: -code-begin-
+   :end-before: -overview-
 
+.. include:: ../README.rst
+   :start-after: -support-
 
-environ.Path
-============
+----
 
-..  autoclass:: environ.environ.Path
+Full Table of Contents
+======================
 
-    ..  py:attribute:: root -> Retrieve absolute path
-    ..  automethod:: __call__
-    ..  automethod:: path
-    ..  automethod:: file
+.. toctree::
+   :maxdepth: 2
 
+   getting-started
+   types
+   tips
+   contributing
 
-Indices and tables
-==================
+.. include:: ../README.rst
+   :start-after: -project-information-
+   :end-before: -support-
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 1
 
+   license
+   changelog

docs/license.rst

@@ -0,0 +1,9 @@
+===================
+License and Credits
+===================
+
+``django-environ`` is open source software licensed under the
+`MIT / X11 License <https://choosealicense.com/licenses/mit/>`_.
+The full license text can be also found in the `source code repository <https://github.com/joke2k/django-environ/blob/main/LICENSE.txt>`_.
+
+.. include:: ../AUTHORS.rst

docs/tips.rst

@@ -0,0 +1,124 @@
+====
+Tips
+====
+
+
+Using unsafe characters in URLs
+===============================
+
+In order to use unsafe characters you have to encode with ``urllib.parse.encode`` before you set into ``.env`` file.
+
+.. code-block:: shell
+
+   DATABASE_URL=mysql://user:%[email protected]:3306/dbname
+
+See https://perishablepress.com/stop-using-unsafe-characters-in-urls/ for reference.
+
+Smart Casting
+=============
+
+``django-environ`` has a "Smart-casting" enabled by default, if you don't provide a ``cast`` type, it will be detected from ``default`` type.
+This could raise side effects (see `#192 <https://github.com/joke2k/django-environ/issues/192>`_).
+To disable it use ``env.smart_cast = False``.
+
+.. note::
+
+   The next major release will disable it by default.
+
+
+Multiple redis cache locations
+==============================
+
+For redis cache, `multiple master/slave or shard locations <http://niwinz.github.io/django-redis/latest/#_pluggable_clients>`_ can be configured as follows:
+
+.. code-block:: shell
+
+   CACHE_URL='rediscache://master:6379,slave1:6379,slave2:6379/1'
+
+
+Email settings
+==============
+
+In order to set email configuration for django you can use this code:
+
+.. code-block:: python
+
+   # The email() method is an alias for email_url().
+   EMAIL_CONFIG = env.email(
+       'EMAIL_URL',
+       default='smtp://user:password@localhost:25'
+   )
+
+   vars().update(EMAIL_CONFIG)
+
+
+SQLite urls
+===========
+
+SQLite connects to file based databases. The same URL format is used, omitting the hostname,
+and using the "file" portion as the filename of the database.
+This has the effect of four slashes being present for an absolute
+
+file path: ``sqlite:////full/path/to/your/database/file.sqlite``.
+
+
+Nested lists
+============
+
+Some settings such as Django's ``ADMINS`` make use of nested lists. You can use something like this to handle similar cases.
+
+.. code-block:: python
+
+   # DJANGO_ADMINS=John:[email protected],Jane:[email protected]
+   ADMINS = [x.split(':') for x in env.list('DJANGO_ADMINS')]
+
+   # or use more specific function
+
+   from email.utils import getaddresses
+
+   # DJANGO_ADMINS=Full Name <[email protected]>,[email protected]
+   ADMINS = getaddresses([env('DJANGO_ADMINS')])
+
+
+Multiline value
+===============
+
+You can set a multiline variable value:
+
+.. code-block:: python
+
+   # MULTILINE_TEXT=Hello\\nWorld
+   >>> print env.str('MULTILINE_TEXT', multiline=True)
+   Hello
+   World
+
+
+Proxy value
+===========
+
+Values that being with a ``$`` may be interpolated. Pass ``interpolate=True`` to
+``environ.Env()`` to enable this feature:
+
+.. code-block:: python
+
+   import environ
+
+   env = environ.Env(interpolate=True)
+
+   # BAR=FOO
+   # PROXY=$BAR
+   >>> print env.str('PROXY')
+   FOO
+
+
+Multiple env files
+==================
+
+It is possible to have multiple env files and select one using environment variables.
+
+.. code-block:: python
+
+   env = environ.Env()
+   env.read_env(env.str('ENV_PATH', '.env'))
+
+Now ``ENV_PATH=other-env ./manage.py runserver`` uses ``other-env`` while ``./manage.py runserver`` uses ``.env``.

docs/types.rst

@@ -0,0 +1,57 @@
+===============
+Supported types
+===============
+
+* ``str``
+* ``bool``
+* ``int``
+* ``float``
+* ``json``
+* ``list``: ``(FOO=a,b,c)``
+* ``tuple``: ``(FOO=(a,b,c))``
+* ``dict``: ``(BAR=key=val,foo=bar)``, ``environ.Env(BAR=(dict, {}))``
+* ``dict``: ``(BAR=key=val;foo=1.1;baz=True)``, ``environ.Env(BAR=(dict(value=unicode, cast=dict(foo=float,baz=bool)), {}))``
+* ``url``
+* ``path``: ``(environ.Path)``
+* ``db_url``
+
+  * PostgreSQL: ``postgres://``, ``pgsql://``, ``psql://`` or ``postgresql://``
+  * PostGIS: ``postgis://``
+  * MySQL: ``mysql://`` or ``mysql2://``
+  * MySQL for GeoDjango: ``mysqlgis://``
+  * MySQL Connector Python from Oracle: ``mysql-connector://``
+  * SQLite: ``sqlite://``
+  * SQLite with SpatiaLite for GeoDjango: ``spatialite://``
+  * Oracle: ``oracle://``
+  * Microsoft SQL Server: ``mssql://``
+  * PyODBC: ``pyodbc://``
+  * Amazon Redshift: ``redshift://``
+  * LDAP: ``ldap://``
+
+* ``cache_url``
+
+  * Database: ``dbcache://``
+  * Dummy: ``dummycache://``
+  * File: ``filecache://``
+  * Memory: ``locmemcache://``
+  * Memcached: ``memcache://``
+  * Python memory: ``pymemcache://``
+  * Redis: ``rediscache://``, ``redis://``, or ``rediss://``
+
+* ``search_url``
+
+  * Elasticsearch: ``elasticsearch://``
+  * Solr: ``solr://``
+  * Whoosh: ``whoosh://``
+  * Xapian: ``xapian://``
+  * Simple cache: ``simple://``
+
+* ``email_url``
+
+  * SMTP: ``smtp://``
+  * SMTP+SSL: ``smtp+ssl://``
+  * SMTP+TLS: ``smtp+tls://``
+  * Console mail: ``consolemail://``
+  * File mail: ``filemail://``
+  * LocMem mail: ``memorymail://``
+  * Dummy mail: ``dummymail://``