update some documentation, added readthedocs config, created extra de…

…ps in setup

.readthedocs.yml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - method: pip
+        path: .
+        extra_requirements:
+            - yaml
+            - semver

.travis.yml

@@ -6,7 +6,7 @@ python:
  - "3.8"
 
 install:
-  - pip install -e . codecov coverage
+  - pip install -e .[semver,yaml] codecov coverage
 
 script:
   - test -n "$TRAVIS_TAG" && sed -e "s/development/${TRAVIS_TAG/v}/g" -i src/glorpen/config/__init__.py || true

doc/code.rst

@@ -11,6 +11,13 @@
 
       Current package version.
 
+:mod:`glorpen.config.config`
+----------------------------
+
+.. automodule:: glorpen.config.config
+   :members:
+   :special-members: __init__
+
 :mod:`glorpen.config.fields.base`
 ---------------------------------
 
@@ -40,13 +47,19 @@
    :special-members: __init__
 
 
-:mod:`glorpen.config.loaders`
------------------------------
+:mod:`glorpen.config.translators.base`
+--------------------------------------
 
-.. automodule:: glorpen.config.loaders
+.. automodule:: glorpen.config.translators.base
    :members:
-   :private-members:
-   :no-undoc-members:
+   :special-members: __init__
+
+:mod:`glorpen.config.translators.yaml`
+--------------------------------------
+
+.. automodule:: glorpen.config.translators.yaml
+   :members:
+   :special-members: __init__
 
 :mod:`glorpen.config.exceptions`
 --------------------------------

doc/index.rst

@@ -6,8 +6,10 @@ Glorpen Config
     :target: https://travis-ci.org/glorpen/glorpen-config
 .. image:: https://readthedocs.org/projects/glorpen-config/badge/?version=latest
     :target: https://glorpen-config.readthedocs.io/en/latest/
+.. image:: https://codecov.io/gh/glorpen/glorpen-config/branch/master/graph/badge.svg
+    :target: https://codecov.io/gh/glorpen/glorpen-config
 
-Config framework for Your projects - with validation, interpolation and value normalization!
+Config framework for Your projects - with validation, interpolation and value normalization. It can even generate default config with help texts!
 
 Official repositories
 =====================
@@ -16,42 +18,57 @@ GitHub: https://github.com/glorpen/glorpen-config
 
 BitBucket: https://bitbucket.org/glorpen/glorpen-config
 
+GitLab: https://gitlab.com/glorpen/glorpen-config
+
 Features
 ========
 
 You can:
 
-- create custom fields for custom data
 - define configuration schema inside Python app
 - convert configuration values to Python objects
-- validate configuration
+- validate user provided data
 - use interpolation to fill config values
-- set default values
+- generate example configuration with help text
+
+How to load data
+----------------
+
+You can use ``Reader`` to read values from arbitrary source and then pass it to :class:`glorpen.config.Config`:
+
+.. code-block:: python
 
-Loading data
-------------
+    from glorpen.config.translators.yaml import YamlReader
+    from glorpen.config import Config
 
-:class:`glorpen.config.Config` uses :mod:`glorpen.config.loaders` to allow loading data from different sources.
+    config = Config(String())
+    config.get(YamlReader("example.yaml").read())
 
-Loaders should accept:
+or with use of :class:`glorpen.config.Translator`:
 
-- path, ``filepath`` constructor argument
-- file-like object, ``fileobj`` constructor argument
+.. code-block:: python
 
-Additionally you can just pass ``dict`` data to config with :meth:`glorpen.config.Config.load_data` or :meth:`glorpen.config.Config.finalize`.
+    from glorpen.config.translators.yaml import YamlReader
+    from glorpen.config import Config, Translator
+
+    translator = Translator(Config(String()))
+    translator.read(YamlReader("example.yaml"))
+
+
+:meth:`glorpen.config.Config.get` accepts anything that is supported by underlying config schema so you can pass ``dict`` or custom objects.
 
 Interpolation
 -------------
 
-You can reuse values from config with ``{{ path.to.value }}`` notation, eg:
+You can reuse values from config with dotted notation, eg: ``{{ path.to.value }}``.
 
 .. code-block:: yaml
 
    project:
       path: "/tmp"
       cache_path: "{{ project.path }}/cache"
 
-String interpolation currently can be used only with :class:`glorpen.config.fields.String` fields.
+See field documentation to find where interpolation is supported.
 
 Normalization and validation
 ----------------------------
@@ -62,18 +79,16 @@ Each field type has own normalization rules, eg. for :class:`glorpen.config.fiel
 
    logging: DEBUG
 
-``config.get("logging")`` would yield value ``10`` as is ``logging.DEBUG``. 
+``config.get(data)`` would yield value ``10`` as in ``logging.DEBUG``. 
 
-Additionally it will raise :class:`glorpen.config.exceptions.ValidationError` if invalid level name is given.
+Additionally it will raise exception if invalid value is provided.
 
-Default values
---------------
+Optional and default values
+---------------------------
 
 Each field can have default value. If no value is given in config but default one is set, it will be used instead.
 
-Default values adhere to same interpolation and normalization rules - each default value is denormalized and then passed to normalizers.
-That way complex object can still profit from config interpolation. There should not be any real impact on performance as it is done only once.
-
+Default values should be already Python values, eg. ``int``, ``str``, objects.
 
 Contents
 ========

setup.py

@@ -48,4 +48,8 @@
     "Topic :: Software Development :: Libraries :: Python Modules",
   ],
   test_suite = "glorpen.config.tests",
+  extras_require = {
+      'semver': ['semver>=2.0,<3.0'],
+      'yaml': ['PyYAML>=5.0,<6.0'],
+  }
 )