Small docs refactor

docs/api.rst

@@ -10,6 +10,7 @@ The ``__init__`` module
 
 .. automodule:: environ
     :members:
+    :special-members:
     :no-undoc-members:
 
 

docs/conf.py

@@ -7,14 +7,16 @@
 # the LICENSE.txt file that was distributed with this source code.
 
 #
-# -- Utils -----------------------------------------------------
+# -- Utils ---------------------------------------------------------
 #
 
 import codecs
 import os
 import sys
 import re
 
+from datetime import date
+
 
 PROJECT_DIR = os.path.abspath('..')
 sys.path.insert(0, PROJECT_DIR)
@@ -38,17 +40,17 @@ def find_version(meta_file):
     if meta_match:
         return meta_match.group(1)
     raise RuntimeError(
-        'Unable to find __version__ string in package meta file')
+        "Unable to find __version__ string in package meta file")
 
 
 #
 # -- Project information -----------------------------------------------------
 #
 
 # General information about the project.
-project = 'django-environ'
-copyright = '2013-2021, Daniele Faraglia and other contributors'
-author = u"Daniele Faraglia"
+project = "django-environ"
+copyright = f'2013-{date.today().year}, Daniele Faraglia and other contributors'
+author = u"Daniele Faraglia \\and Serghei Iakovlev"
 
 #
 # -- General configuration ---------------------------------------------------
@@ -79,7 +81,7 @@ def find_version(meta_file):
 
 # The version info
 # The short X.Y version.
-release = find_version('environ/__init__.py')
+release = find_version(os.path.join("environ", "__init__.py"))
 version = release.rsplit(u".", 1)[0]
 # The full version, including alpha/beta/rc tags.
 
@@ -89,13 +91,13 @@ def find_version(meta_file):
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-# default_role = None
+default_role = "any"
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
 #
-# -- Options for linkcheck ----------------------------------------------------
+# -- Options for linkcheck ---------------------------------------------------
 #
 
 linkcheck_ignore = [
@@ -104,7 +106,7 @@ def find_version(meta_file):
 ]
 
 #
-# -- Options for nitpick ----------------------------------------------------
+# -- Options for nitpick -----------------------------------------------------
 #
 
 # In nitpick mode (-n), still ignore any of the following "broken" references
@@ -115,13 +117,15 @@ def find_version(meta_file):
 #
 # -- Options for extlinks ----------------------------------------------------
 #
+
 extlinks = {
     "pypi": ("https://pypi.org/project/%s/", ""),
 }
 
 #
 # -- Options for intersphinx -------------------------------------------------
 #
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master", None),
@@ -130,14 +134,15 @@ def find_version(meta_file):
 #
 # -- Options for TODOs -------------------------------------------------------
 #
+
 todo_include_todos = True
 
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
 
 # html_favicon = None
 
 html_theme = "furo"
-html_title = "django-environ"
+html_title = project
 
 html_theme_options = {}
 
@@ -173,7 +178,7 @@ def find_version(meta_file):
 htmlhelp_basename = "django-environ-doc"
 
 #
-# -- Options for manual page output ---------------------------------------
+# -- Options for manual page output ------------------------------------------
 #
 
 # One entry per manual page. List of tuples
@@ -183,7 +188,7 @@ def find_version(meta_file):
 ]
 
 #
-# -- Options for Texinfo output -------------------------------------------
+# -- Options for Texinfo output ----------------------------------------------
 #
 
 # Grouping the document tree into Texinfo files. List of tuples

docs/faq.rst

@@ -0,0 +1,31 @@
+===
+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 :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.
+   For details see ":ref:`multiple-env-files-label`".
+
+#. **What (where) is the root part of the project, is it part of the project where are settings?**
+
+   Where your ``manage.py`` file is (that is your project root directory).
+
+#. **What kind of file should .env be?**
+
+   ``.env`` is a plain text file.
+
+#. **Should name of the file be simply .env (or something.env)?**
+
+   Just ``.env``. However, this is not a strict rule, but just a common
+   practice. Formally, you can use any filename.
+
+#. **Is .env file going to be imported in settings file?**
+
+   No need to import, ``django-environ`` automatically picks variables
+   from there.