[DIN-30] Update project documentations (#9)

Lucas Fonseca · web-flow · commit a4fa092aab93 · 2022-08-15T16:41:05.000-03:00
* Update requirements
* Update docs source
* Update links
* Update pr template
diff --git a/.github/pull-request-template.md b/.github/pull-request-template.md
@@ -21,7 +21,7 @@ _Please delete options that are not relevant._
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] This change requires a documentation update
+- [ ] Documentation
 - [ ] Release
 
 ## How everything was tested? :straight_ruler:
diff --git a/docs/requirements.docs.txt b/docs/requirements.docs.txt
@@ -3,6 +3,4 @@ recommonmark==0.6.0
 Sphinx==3.1.1
 sphinx-rtd-theme==0.4.3
 sphinxemoji==0.1.6
-typing-extensions==3.7.4.2
-thrift==0.13.0
-
+typing-extensions==3.7.4.2
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,3 +1,4 @@
+"""Sphinx Configuration."""
 # -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
@@ -22,12 +23,12 @@
 
 project = "Hierarchical Conf"
 copyright = "2022, QuintoAndar"
-author = "QuintoAndar"
+author = "Data Engineering Team"
 
 # The short X.Y version
-version = "0.0"
+version = "1.0"
 # The full version, including alpha/beta/rc tags
-release = "0.0.1"
+release = "1.0.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -41,20 +42,22 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
-    "sphinx.ext.todo",
+    "recommonmark",
+    "sphinx_rtd_theme",
+    "sphinx.ext.napoleon",
     "sphinx.ext.coverage",
-    "sphinx.ext.viewcode",
+    "sphinxemoji.sphinxemoji",
 ]
 
+sphinxemoji_style = "twemoji"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
 master_doc = "index"
@@ -64,7 +67,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -80,6 +83,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
+# html_theme = 'alabaster'
 html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -133,7 +137,7 @@
 latex_documents = [
     (
         master_doc,
-        "hierarchical_conf.tex",
+        "HierarchicalConf.tex",
         "Hierarchical Conf Documentation",
         "QuintoAndar",
         "manual",
@@ -149,7 +153,7 @@
     (
         master_doc,
         "hierarchical_conf",
-        "Hierarchical Conf Documentation",
+        "HierarchicalConf Documentation",
         [author],
         1,
     )
@@ -164,10 +168,10 @@
 texinfo_documents = [
     (
         master_doc,
-        "hierarchical_conf",
-        "hierarchical_conf Documentation",
+        "Hierarchical Conf",
+        "Hierarchical Conf Documentation",
         author,
-        "hierarchical_conf",
+        "Hierarchical Conf",
         "One line description of project.",
         "Miscellaneous",
     ),
@@ -193,8 +197,3 @@
 
 
 # -- Extension configuration -------------------------------------------------
-
-# -- Options for todo extension ----------------------------------------------
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
diff --git a/docs/source/getstarted.md b/docs/source/getstarted.md
@@ -0,0 +1,35 @@
+# Getting Started
+
+Hierarchical Conf depends on **Python 3.7+**.
+
+[Python Package Index](https://pypi.org/project/hierarchical-conf/) hosts reference to a pip-installable module of this library, using it is as straightforward as including it on your project's requirements.
+
+```bash
+pip install hierarchical-conf
+```
+
+Or after listing `hierarchical-conf` in your `requirements.txt` file:
+
+```bash
+pip install -r requirements.txt
+```
+
+## Discovering Hierarchical Conf
+
+Click on the following links to open the [examples](https://github.com/quintoandar/hierarchical-conf/tree/main/examples):
+
+**[#1 Get configurations using one file](https://github.com/quintoandar/hierarchical-conf/blob/main/examples/get_conf_with_one_file.py)**
+
+**[#2 Get configurations using two (or more) files](https://github.com/quintoandar/hierarchical-conf/blob/main/examples/get_conf_with_two_files.py)**
+
+**[#3 Get specific configurations (runnable)](https://github.com/quintoandar/hierarchical-conf/blob/main/examples/get_specific_confs_runnable.py)**
+
+**[#4 Get specific configurations with overload (runnable)](https://github.com/quintoandar/hierarchical-conf/blob/main/examples/precedence_example/get_specific_confs_with_precendence_runnable.py)**
+
+
+## Available methods
+
+The features of this package can be accessed through:
+
+- [`configs`](hierarchical_conf.html#hierarchical_conf.hierarchical_conf.HierarchicalConf.configs)
+- [`get_config`](hierarchical_conf.html#hierarchical_conf.hierarchical_conf.HierarchicalConf.get_config)
diff --git a/docs/source/hierarchical_conf.rst b/docs/source/hierarchical_conf.rst
@@ -0,0 +1,20 @@
+hierarchical\_conf package
+==========================
+
+Submodules
+----------
+
+
+.. automodule:: hierarchical_conf.hierarchical_conf
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: hierarchical_conf
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,16 +1,73 @@
-.. hierarchical_confAPIClientPython documentation master file.
+Hierarchical Conf
+===========================
+Made with |:heart:| by the **Data Engineering** team from `QuintoAndar <https://github.com/quintoandar/>`_.
 
-Welcome to Hierarchical Conf documentation!
-=============================================================================================
+A library for loading configurations (or other metadata) hierarchically based on the current environment.
+
+How to use
+----------
+
+**Short**
+
+An example of how to use the library getting configurations:
+
+.. code-block:: python
+
+    from hierarchical_conf.hierarchical_conf import HierarchicalConf
+
+    hierarchical_conf = HierarchicalConf(searched_paths=[PROJECT_ROOT])
+    my_config = hierarchical_conf.get_config("my_config_key")
+
+
+**Long**
+
+This tool retrieve the configurations from (YAML) files according to the current
+environment and files precedence.
+
+It receives a list of paths and searches each one for environment configuration files in an **orderly
+fashion**, loading them when found and **overwriting duplicated** configuration keys by the value of the key
+available in the file loaded at last.
+The YAML configuration files are expected to be named with prefixes based on the working environment,
+retrieved by the value of a pre-existent operational system environment's variable named ``ENVIRONMENT``.
+
+E.g.: Given the respective environments ``dev`` and ``production`` configuration files below:
+
+dev_conf.yml:
+
+.. code-block:: yaml
+
+    foo: bar_dev
+    foo2: bar_dev2
+
+production_conf.yml:
+
+.. code-block:: yaml
+
+    foo: bar_prod
+    foo2: bar_prod2
+
+and given we are at development environment (``ENVIRONMENT=dev``), the following code will load the
+configuration file from the development environment file (``/my_path/dev_conf.yml``).
+
+.. code-block:: python
+
+    hconf = HierarchicalConf(conf_files_paths=['/my_path/'])
+    foo_conf = hconf.get_config("foo")
+    print(foo_conf)
+    # prints: bar_dev
+
+Given ``ENVIRONMENT=production``, the code above will load the configuration file from
+the production environment file (``/my_path/production_conf.yml``) and print: ``bar_prod``.
+
+To learn more use cases in practice (and about the keys overwriting), see `Hierarchical Conf examples <https://github.com/quintoandar/hierarchical-conf/tree/main/examples>`_.
+
+
+Navigation
+^^^^^^^^^^
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
 
-Indices and tables
-==================
+   getstarted
+   modules
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+API Specification
+=================
+
+.. toctree::
+   :maxdepth: 4
+
+   hierarchical_conf
diff --git a/docs/source/quintoandar_hierarchical_conf.rst b/docs/source/quintoandar_hierarchical_conf.rst
diff --git a/hierarchical_conf/hierarchical_conf.py b/hierarchical_conf/hierarchical_conf.py
@@ -22,7 +22,7 @@ def __init__(self, searched_paths: List[str]) -> None:
 
     @property
     def configs(self) -> Dict[str, Union[str, List[Any], Dict[str, Any]]]:
-        """All loaded configurations."""
+        """Returns all loaded configurations."""
         return self._configs.copy()
 
     @property
diff --git a/requirements.dev.txt b/requirements.dev.txt
@@ -1,8 +1 @@
-bump2version==0.5.11
-wheel==0.33.6
-coverage==5.5
-pytest==4.6.5
-pytest-runner==5.1
-pytest-cov==2.8.1
-Sphinx==1.8.5
-sphinx_rtd_theme==0.4.3
+twine==3.1.1
