Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@manuphatak
manuphatak committed Dec 19, 2015
1 parent aa4a780 commit f02308b
Show file tree
Hide file tree
Showing 5 changed files with 261 additions and 41 deletions.
99 changes: 75 additions & 24 deletions CONTRIBUTING.rst
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,35 @@
.. highlight:: shell
.. START Source defined in docs/github_docs.py
.. This document was procedurally generated by docs/github_docs.py on Saturday, December 19, 2015
.. END Source defined in docs/github_docs.py
.. START Source defined in docs/github_docs.py
.. role:: mod(literal)
.. role:: func(literal)
.. role:: data(literal)
.. role:: const(literal)
.. role:: class(literal)
.. role:: meth(literal)
.. role:: attr(literal)
.. role:: exc(literal)
.. role:: obj(literal)
.. role:: envvar(literal)


.. END Source defined in docs/github_docs.py
.. START Source defined in docs/source/contributing.rst
============
Contributing
============

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.

You can contribute in many ways:

Expand All @@ -25,17 +50,21 @@ If you are reporting a bug, please include:
Fix Bugs
~~~~~~~~

Look through the GitHub issues for bugs. Anything tagged with "bug" is open to whoever wants to implement it.
Look through the GitHub issues for bugs. Anything tagged with "bug"
is open to whoever wants to implement it.

Implement Features
~~~~~~~~~~~~~~~~~~

Look through the GitHub issues for features. Anything tagged with "feature" is open to whoever wants to implement it.
Look through the GitHub issues for features. Anything tagged with "feature"
is open to whoever wants to implement it.

Write Documentation
~~~~~~~~~~~~~~~~~~~

json_config could always use more documentation, whether as part of the official json_config docs, in docstrings, or even on the web in blog posts, articles, and such.
json_config could always use more documentation, whether as part of the
official json_config docs, in docstrings, or even on the web in blog posts,
articles, and such.

Submit Feedback
~~~~~~~~~~~~~~~
Expand All @@ -46,57 +75,79 @@ If you are proposing a feature:

* Explain in detail how it would work.
* Keep the scope as narrow as possible, to make it easier to implement.
* Remember that this is a volunteer-driven project, and that contributions are welcome :)
* Remember that this is a volunteer-driven project, and that contributions
are welcome :)

Get Started!
------------

Ready to contribute? Here's how to set up `json_config` for local development.

1. Fork_ the `json_config` repo on GitHub.
2. Clone your fork locally::
1. Fork the `json_config` repo on GitHub.
2. Clone your fork locally

.. code-block:: shell
$ git clone git@github.com:your_name_here/json_config.git
3. Create a branch for local development::
3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development

.. code-block:: shell
$ git checkout -b feature/name-of-your-feature development
$ mkvirtualenv json_config
$ cd json_config/
$ python setup.py develop
$ git checkout -b hotfix/name-of-your-bugfix development
4. Create a branch for local development

.. code-block:: shell
$ git checkout -b feature/name-of-your-feature
$ git checkout -b hotfix/name-of-your-bugfix
Now you can make your changes locally.

4. When you're done making changes, check that your changes pass style and unit tests, including testing other Python versions with tox::
5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox

.. code-block:: shell
$ flake8 json_config tests
$ python setup.py test
$ tox
To get tox, just pip install it.
To get flake8 and tox, just pip install them into your virtualenv.
5. Commit your changes and push your branch to GitHub::
6. Commit your changes and push your branch to GitHub

.. code-block:: shell
$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
6. Submit a pull request through the GitHub website.

.. _Fork: https://github.com/bionikspoon/json_config/fork
7. Submit a pull request through the GitHub website.

Pull Request Guidelines
-----------------------

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.7, and 3.4, and for PyPy.

Check https://travis-ci.org/bionikspoon/json_config under pull requests for active pull requests or run the ``tox`` command and make sure that the tests pass for all supported Python versions.

2. If the pull request adds functionality, the docs should be updated. Put
your new functionality into a function with a docstring, and add the
feature to the list in README.rst.
3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4, 3.5, and PyPy. Check
https://travis-ci.org/bionikspoon/json_config/pull_requests
and make sure that the tests pass for all supported Python versions.

Tips
----

To run a subset of tests::
To run a subset of tests

.. code-block:: shell
$ py.test tests/test_json_config.py
$ py.test test/test_json_config.py
.. END Source defined in docs/source/contributing.rst
170 changes: 170 additions & 0 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,175 @@
.. START Source defined in docs/github_docs.py
.. This document was procedurally generated by docs/github_docs.py on Saturday, December 19, 2015
.. END Source defined in docs/github_docs.py
.. START Source defined in docs/github_docs.py
.. role:: mod(literal)
.. role:: func(literal)
.. role:: data(literal)
.. role:: const(literal)
.. role:: class(literal)
.. role:: meth(literal)
.. role:: attr(literal)
.. role:: exc(literal)
.. role:: obj(literal)
.. role:: envvar(literal)


.. END Source defined in docs/github_docs.py
.. START Source defined in docs/source/readme_title.rst
===============================
json_config
===============================

.. image:: https://badge.fury.io/py/json_config.svg
:target: https://pypi.python.org/pypi/json_config/
:alt: Latest Version

.. image:: https://img.shields.io/pypi/status/json_config.svg
:target: https://pypi.python.org/pypi/json_config/
:alt: Development Status

.. image:: https://travis-ci.org/bionikspoon/json_config.svg?branch=develop
:target: https://travis-ci.org/bionikspoon/json_config?branch=develop
:alt: Build Status

.. image:: https://coveralls.io/repos/bionikspoon/json_config/badge.svg?branch=develop
:target: https://coveralls.io/github/bionikspoon/json_config?branch=develop&service=github
:alt: Coverage Status

.. image:: https://readthedocs.org/projects/json_config/badge/?version=develop
:target: https://json_config.readthedocs.org/en/develop/?badge=develop
:alt: Documentation Status


A convenience utility for working with JSON config files.


.. END Source defined in docs/source/readme_title.rst
.. START Source defined in docs/source/readme_features.rst
Features
--------

- Documentation: https://json_config.readthedocs.org
- Open Source: https://github.com/bionikspoon/json_config
- MIT license

..
- Automatically syncs file on changes.
- Automatically handles complicated nested data structures.
- Lightweight (<5KB) and Fast.
- Takes advantage of Python's native dictionary syntax.
- Tested against python 2.7, 3.2, 3.3, 3.4, and PYPY.
- Saves silently in the background.
- Unit Tested with high coverage.

.. code-block:: python
>>> import json_config
>>> config = json_config.connect('categories.json')
>>> config
{}
>>> config['comics']['dc']['batman']['antagonists'] = ['Scarecrow', 'The Joker', 'Bane']
>>> config['comics']['marvel']['ironman']['antagonists'] = 'Ultron'
>>> config
{
"comics": {
"dc": {
"batman": {
"antagonists": [
"Scarecrow",
"The Joker",
"Bane"
]
}
},
"marvel": {
"ironman": {
"antagonists": "Ultron"
}
}
}
}
.. END Source defined in docs/source/readme_features.rst
.. START Source defined in docs/source/installation.rst
============
Installation
============

At the command line either via easy_install or pip

.. code-block:: shell
$ pip install json_config
.. code-block:: shell
$ easy_install json_config
Or, if you have virtualenvwrapper installed

.. code-block:: shell
$ mkvirtualenv json_config
$ pip install json_config
**Uninstall**

.. code-block:: shell
$ pip uninstall json_config
.. END Source defined in docs/source/installation.rst
.. START Source defined in docs/source/usage.rst
=====
Usage
=====

To use json_config in a project:

.. code-block:: python
import json_config
config = json_config.connect('config.json')
config['root'] = '/var/www/html/'
print config['root'] # '/var/www/html/'
print config # { "root": "/var/www/html" }
.. END Source defined in docs/source/usage.rst
.. START Source defined in docs/source/readme_credits.rst
Credits
-------

Tools used in rendering this package:

* Cookiecutter_
* `bionikspoon/cookiecutter-pypackage`_ forked from `audreyr/cookiecutter-pypackage`_

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`bionikspoon/cookiecutter-pypackage`: https://github.com/bionikspoon/cookiecutter-pypackage
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


.. END Source defined in docs/source/readme_credits.rst
20 changes: 13 additions & 7 deletions docs/source/json_config.rst
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,28 @@
json_config package
===================

.. automodule:: json_config
:members:
:undoc-members:
:show-inheritance:

Submodules
----------

json_config.configuration module
--------------------------------
json_config._compat module
--------------------------

.. automodule:: json_config.configuration
.. automodule:: json_config._compat
:members:
:undoc-members:
:show-inheritance:

json_config.configuration module
--------------------------------

Module contents
---------------

.. automodule:: json_config
.. automodule:: json_config.configuration
:members:
:undoc-members:
:show-inheritance:


7 changes: 0 additions & 7 deletions docs/source/modules.rst
View file

This file was deleted.

Loading

0 comments on commit f02308b

Please sign in to comment.