Prettify distro -j's output and add more elaborate docs

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# General
+
+* Contributing to distro identification currently doesn't have any specific standards and rather depends on the specific implementation.
+* A 100% coverage is expected for each PR unless explicitly authorized by the reviewer.
+* Please try to maintain maximum code-health (via landscape.io).
+
+# Contributing distro specific tests
+
+Distro's tests are implemented via a standardized framework under `tests/test_distro.py`
+
+For each distribution, tests should be added in the relevant class according to which distribution file(s) exists on it, so, for example, tests should be added under `TestOSRelease` where `/etc/os-release` is available.
+
+The tests must be self-contained, meaning that the release files for the distribution should be maintained in the repository under `tests/resources/distros/distribution_name+distribution_version`.
+
+A tests method would like somewhat like this:
+
+```python
+def test_centos7_os_release(self):
+    desired_outcome = {
+        'id': 'centos',
+        'name': 'CentOS Linux',
+        'pretty_name': 'CentOS Linux 7 (Core)',
+        'version': '7',
+        'pretty_version': '7 (Core)',
+        'best_version': '7',
+        'like': 'rhel fedora',
+        'codename': 'Core'
+    }
+    self._test_outcome(desired_outcome)
+```
+
+The framework will automatically try to pick up the relevant file according to the method's name (`centos7` meaning the folder should be named `centos7` as well) and compare the `desired_outcome` with the parsed files found under the test dir.
+
+The exception to the rule is under the `TestDistroRelease` test class which should look somewhat like this:
+
+```python
+def test_centos5_dist_release(self):
+    desired_outcome = {
+        'id': 'centos',
+        'name': 'CentOS',
+        'pretty_name': 'CentOS 5.11 (Final)',
+        'version': '5.11',
+        'pretty_version': '5.11 (Final)',
+        'best_version': '5.11',
+        'codename': 'Final',
+        'major_version': '5',
+        'minor_version': '11'
+    }
+    self._test_outcome(desired_outcome, 'centos', '5')
+```
+
+Where the name of the method is not indicative of the lookup folder but rather tha two last arguments in `_test_outcome`.
+
+A test case is mandatory under `TestOverall` for a PR to be complete.

README.md

@@ -1,5 +1,5 @@
 Distro - a Linux OS platform information API
-========================================================
+============================================
 
 [![Build Status](https://travis-ci.org/nir0s/distro.svg?branch=master)](https://travis-ci.org/nir0s/distro)
 [![Build status](https://ci.appveyor.com/api/projects/status/e812qjk1gf0f74r5/branch/master?svg=true)](https://ci.appveyor.com/project/nir0s/distro/branch/master)
@@ -12,28 +12,13 @@ Distro - a Linux OS platform information API
 [![Latest Github Release](https://readthedocs.org/projects/distro/badge/?version=stable)](http://distro.readthedocs.io/en/latest/)
 
 
-The `distro` (for: Linux Distribution) package provides information about the
+`distro` (for: Linux Distribution) provides information about the
 Linux distribution it runs on, such as a reliable machine-readable ID, or
 version information.
 
 It is a renewed alternative implementation for Python's
 original `platform.linux_distribution` function, but it also provides much more
-functionality.
-An alternative implementation became necessary because Python 3.5 deprecated
-this function, and Python 3.7 is expected to remove it altogether.
-Its predecessor function `platform.dist` was already deprecated since
-Python 2.6 and is also expected to be removed in Python 3.7.
-Still, there are many cases in which access to that information is needed.
-See [Python issue 1322](https://bugs.python.org/issue1322) for more
-information.
-
-The `distro` package implements a robust and inclusive way of retrieving the
-information about a Linux distribution based on new standards and old methods,
-namely from these data sources (from high to low precedence):
-
-* The os-release file `/etc/os-release`, if present.
-* The output of the `lsb_release` command, if available.
-* The distro release file (`/etc/*(-|_)(release|version)`), if present.
+functionality which isn't necessarily Python bound like a command-line interface.
 
 
 ## Installation
@@ -50,20 +35,6 @@ Installation of the latest development version:
 pip install https://github.com/nir0s/distro/archive/master.tar.gz
 ```
 
-## Documentation
-
-The API documentation for the `distro` package is on RTD:
-[latest API documentation](http://distro.readthedocs.org/en/latest/).
-
-## Python and Distribution Support
-
-The `distro` package is supported on Python 2.6, 2.7, 3.4 and 3.5, and on
-any Linux distribution that provides one or more of the data sources
-used by this package.
-
-This package is tested on Python 2.6, 2.7, 3.4 and 3.5, with test
-data that mimics the exact behavior of the data sources of
-[a number of Linux distributions](https://github.com/nir0s/distro/tree/master/tests/resources/distros).
 
 ## Usage
 
@@ -74,17 +45,59 @@ Version: 2015.10 (ISO-Rolling)
 Codename: ISO-Rolling
 
 $ distro -j
-{"codename": "ISO-Rolling", "version": "2015.10", "like": "arch", "version_parts": {"major": "2015", "build_number": "", "minor": "10"}, "id": "antergos"}
+{
+    "codename": "ISO-Rolling", 
+    "id": "antergos", 
+    "like": "arch", 
+    "version": "16.9", 
+    "version_parts": {
+        "build_number": "", 
+        "major": "16", 
+        "minor": "9"
+    }
+}
+
 
 $ python
 >>> import distro
 >>> distro.linux_distribution(full_distribution_name=False)
 '('centos', '7.1.1503', 'Core')'
 ```
 
-Several more functions are available. For a complete description of the
+
+## Documentation
+
+On top of the aforementioned API, several more functions are available. For a complete description of the
 API, see the [latest API documentation](http://distro.readthedocs.org/en/latest/).
 
+## Background
+
+An alternative implementation became necessary because Python 3.5 deprecated
+this function, and Python 3.7 is expected to remove it altogether.
+Its predecessor function `platform.dist` was already deprecated since
+Python 2.6 and is also expected to be removed in Python 3.7.
+Still, there are many cases in which access to that information is needed.
+See [Python issue 1322](https://bugs.python.org/issue1322) for more
+information.
+
+The `distro` package implements a robust and inclusive way of retrieving the
+information about a Linux distribution based on new standards and old methods,
+namely from these data sources (from high to low precedence):
+
+* The os-release file `/etc/os-release`, if present.
+* The output of the `lsb_release` command, if available.
+* The distro release file (`/etc/*(-|_)(release|version)`), if present.
+
+
+## Python and Distribution Support
+
+`distro` is supported and tested on Python 2.6, 2.7, 3.4, 3.5 and PyPy and on
+any Linux distribution that provides one or more of the data sources
+covered.
+
+This package is tested with test data that mimics the exact behavior of the data sources of [a number of Linux distributions](https://github.com/nir0s/distro/tree/master/tests/resources/distros).
+
+
 ## Testing
 
 ```shell
@@ -94,11 +107,14 @@ pip install tox
 tox
 ```
 
+
 ## Contributions
 
 Pull requests are always welcome to deal with specific distributions or just
 for general merriment.
 
+See [CONTRIBUTIONS](https://github.com/nir0s/distro/blob/master/CONTRIBUTING.md) for contribution info.
+
 Reference implementations for supporting additional distributions and file
 formats can be found here:
 

distro.py

@@ -1065,7 +1065,7 @@ def main():
     args = parser.parse_args()
 
     if args.json:
-        logger.info(json.dumps(info()))
+        logger.info(json.dumps(info(), indent=4, sort_keys=True))
     else:
         logger.info('Name: %s', name(pretty=True))
         distribution_version = version(pretty=True)