updating latest version with up to date documentation

docs/source/changelog.rst

@@ -1,7 +1,12 @@
 Version history
 ================
 
+1.0.2
+------
+
+- Minor fixes and documentation updates.
+
 1.0
 --------
 
-- initial release
+- Initial release.

docs/source/configuration.rst

@@ -1,4 +1,23 @@
 Configuration
 =============
 
-.. todo:: fill in configuration options
+panaetius is fairly easy to configure. There are just a couple of options to be aware of.
+
+header.py
+----------
+
+You should set a ``__header__.py`` next to your script or module.
+
+This ``__header__.py`` should contain a ``__header__`` variable that sets the name of your project/script.
+
+E.g a ``__header__.py`` for the module ``plex_posters`` would look like:
+
+.. code-block:: python
+
+    __header__ = 'plex_posters' 
+
+If you are writing a script, simply place this ``__header__.py`` along side your script. Panaetius will pick this up when the script is ran.
+
+If you are writing a module, you can either place the ``__header__.py`` alongside the script that uses your module. If this is not possible, panaetius will set the default ``__header__`` variable to the name of the virtualenv that the script is activated from.
+
+If neither of the above aren't possible (say your script is running in a lambda on AWS), then ``__header__`` will be set to the default of ``panaetius``.

docs/source/introduction.rst

@@ -1,4 +1,154 @@
 panaetius
 ==========
 
-tbc
+.. image:: https://img.shields.io/readthedocs/panaetius?style=for-the-badge   :target: https://panaetius.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
+.. image:: https://img.shields.io/github/v/tag/dtomlinson91/panaetius?style=for-the-badge   :alt: GitHub tag (latest by date)
+
+.. image:: https://img.shields.io/github/commit-activity/m/dtomlinson91/panaetius?style=for-the-badge   :alt: GitHub commit activity
+
+.. image:: https://img.shields.io/github/issues/dtomlinson91/panaetius?style=for-the-badge   :alt: GitHub issues
+
+.. image:: https://img.shields.io/github/license/dtomlinson91/panaetius?style=for-the-badge   :alt: GitHubtbc
+
+Python module to gracefully handle a .config file/environment variables for scripts, with built in masking for sensitive options. Provides a Splunk friendly formatted logger instance.
+
+Usage
+------
+
+Setting a config file
+~~~~~~~~~~~~~~~~~~~~~~
+
+The main functionality of ``panaetius`` is using a config file to store variables.
+
+Your ``config.toml`` can be created and found in ~/.config/__header__/config.toml where __header__ is equal to the variable configured/set. `See how to configure`_ this variable in the configuration section of panaetius.
+
+.. _See how to configure: https://panaetius.readthedocs.io/en/latest/configuration.html#header-py
+
+Setting values in a config.toml/environment variables
+#######################################################
+
+A ``config.toml`` can be created in the default folder for the module. In this example this would be found in ``~/.config/example_module/config.toml``. 
+
+An example ``config.toml`` could look like:
+
+.. code-block:: toml
+
+    [example_module]
+    test = "a6cbf36649b029f3618a0cc1"
+
+    [example_module.logging]
+    path = "~/.config/example_module"
+    level = "DEBUG"
+
+    [example_module.foo]
+    bar = "6b3b96815218960ceaf7cceb"
+
+These are equivalent to the environment variables:
+
+.. code-block:: bash
+
+    EXAMPLE_MODULE_TEST
+    EXAMPLE_MODULE_LOGGING_PATH
+    EXAMPLE_MODULE_LOGGING_LEVEL
+    EXAMPLE_MODULE_FOO_BAR
+
+
+.. Attention:: 
+    Environment variables take precedent over the ``config.toml``. If both are set then the environment variable will be used.
+
+You can overwrite the ``config.toml`` location by setting the environment variable:
+
+.. code-block:: bash
+
+    DEFAULT_CONFIG_PATH = "~/path/to/config"
+
+
+Setting values in your code
+############################
+
+Values in a ``config.toml`` or from an environment variable need to be set in your work in order for you to use them. You can do this easily by
+
+- importing panaetius.
+- using the :func:`panaetius.library.set_config` function.
+  
+E.g your script could contain:
+
+.. code-block:: python
+
+    import panaetius
+    panaetius.set_config(panaetius.CONFIG, 'logging.path')
+
+.. Note::
+
+    The ``key`` attribute in :func:`panaetius.library.set_config` is specified as a string, with the hirearchy in the config file split with a ``.``.
+
+.. Important::
+
+    The default value for a variable defined using :func:`panaetius.library.set_config` is ``None``. See the documentation of this function to see all the options available.
+
+
+Accessing values
+#################
+
+You can then access the result of this variable later in your code:
+
+.. code-block:: python
+
+    panaetius.CONFIG.logging_path
+
+
+Logging
+~~~~~~~~
+
+In order to save to disk, you need to specify a path for the log file in the config file/environment variable. There is no need to register this with :func:`panaetius.library.set_config` as ``panaetius`` will do this automatically.
+
+There are other options available for you to configure a logger. These are (including the default values which can be overwritten):
+
+.. code-block:: toml
+
+    [example_module.logging]
+    backup_count = 3
+    format = "{\n\t"time": "%(asctime)s",\n\t"file_name": "%(filename)s",'
+    '\n\t"module": "%(module)s",\n\t"function":"%(funcName)s",\n\t'
+    '"line_number": "%(lineno)s",\n\t"logging_level":'
+    '"%(levelname)s",\n\t"message": "%(message)s"\n}"
+    level = "INFO" # Level should be in CAPS
+    rotate_bytes = 512000
+
+You can use the logger in your code by:
+
+.. code-block:: python
+
+    panaetius.logger.info('some log message')
+
+which gives an output of:
+
+.. code-block:: json
+
+    {
+        "time": "2020-01-13 23:07:17,913",
+        "file_name": "test.py",
+        "module": "test",
+        "function":"<module>",
+        "line_number": "33",
+        "logging_level":"INFO",
+        "message": "some logging message"
+    }
+
+
+Importing and using the api
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See `panaetius api page`_ on how to use and import the module.
+
+.. _panaetius api page: https://panaetius.readthedocs.io/en/latest/modules/panaetius.html
+
+
+Configuration
+---------------
+
+See `configuration page`_ on how to configure ``panaetius``.
+
+.. _configuration page: https://panaetius.readthedocs.io/en/latest/configuration.html

docs/source/modules/modules.rst

@@ -1,7 +0,0 @@
-panaetius
-=========
-
-.. toctree::
-   :maxdepth: 4
-
-   panaetius

docs/source/modules/panaetius.config.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius.config`
--------------------------------------
+panaetius.config :modname:`panaetius.config`
+---------------------------------------------
 
 .. automodule:: panaetius.config
    :members:

docs/source/modules/panaetius.config_inst.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius.config_inst`
----------------------------------------
+panaetius.config_inst :modname:`panaetius.config_inst`
+--------------------------------------------------------
 
 .. automodule:: panaetius.config_inst
    :members:

docs/source/modules/panaetius.db.rst

@@ -1,6 +1,6 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius.db`
+panaetius.db :modname:`panaetius.db`
 -------------------------------------
 
 .. automodule:: panaetius.db

docs/source/modules/panaetius.header.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius.header`
--------------------------------------
+panaetius.header :modname:`panaetius.header`
+---------------------------------------------
 
 .. automodule:: panaetius.header
    :members:

docs/source/modules/panaetius.library.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius.library`
--------------------------------------
+panaetius.library :modname:`panaetius.library`
+------------------------------------------------
 
 .. automodule:: panaetius.library
    :members:

docs/source/modules/panaetius.logging.rst

@@ -1,7 +1,7 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius.logging`
--------------------------------------
+panaetius.logging :modname:`panaetius.logging`
+----------------------------------------------
 
 .. automodule:: panaetius.logging
    :members:

docs/source/modules/panaetius.rst

@@ -1,21 +1,66 @@
 .. include:: ../global.rst
 
-Config :modname:`panaetius`
--------------------------------------
+*********
+panaetius
+*********
 
-.. automodule:: panaetius
-   :members:
-   :undoc-members:
-   :show-inheritance:
+API
+===
 
-Submodules
-----------
+The following is availble by importing the module:
 
-.. toctree::
+.. code-block:: python
 
-   panaetius.config
-   panaetius.config_inst
-   panaetius.db
-   panaetius.header
-   panaetius.library
-   panaetius.logging
+    import panaetius
+
+
+panaetius.CONFIG
+----------------
+
+:obj:`panaetius.CONFIG` provides an instance of :class:`panaetius.config.Config`
+
+
+panaetius.set_config()
+-----------------------
+
+Conveniently provides :func:`panaetius.library.set_config` 
+
+Use in your module/script with:
+
+.. code-block:: python
+
+    panaetius.set_config(panaetius.CONFIG, 'aws.secret_key', str, mask=True)    
+
+
+panaetius.CONFIG.aws_secret_key
+-------------------------------
+
+Conveniently provides access to all attributes that have been declared with :func:`panaetius.library.set_config`:
+
+.. code-block:: python
+
+    my_secret_key = panaetius.CONFIG.aws_secret_key
+
+
+panaetius.logger
+-----------------
+
+:obj:`panaetius.logger` provides a logger instance already formatted with a nice json output.
+
+.. code-block:: python
+
+    panaetius.logger.info('some logging message')
+
+This gives a logger output of:
+
+.. code-block:: json
+
+    {
+        "time": "2020-01-13 23:07:17,913",
+        "file_name": "test.py",
+        "module": "test",
+        "function":"<module>",
+        "line_number": "33",
+        "logging_level":"INFO",
+        "message": "some logging message"
+    }

docs/source/toc.rst

@@ -25,4 +25,3 @@
    modules/panaetius.header.rst
    modules/panaetius.library.rst
    modules/panaetius.logging.rst
-   modules/panaetius.rst