aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-02-02 16:39:48 -0600
committerEugene Triguba <eugenetriguba@gmail.com>2020-02-02 16:39:48 -0600
commiteffe00be8f1413ed57e3dac2ff73e012696831a7 (patch)
tree488849998fd0e6bd6abc1251d02891bd039cd448
parentAdd sphinx-quickstart (diff)
downloadconfig-file-effe00be8f1413ed57e3dac2ff73e012696831a7.zip
Move some of the docs over to sphinx on a RTD theme
-rw-r--r--README.md137
-rw-r--r--README.rst34
-rw-r--r--docs/source/api-reference.rst2
-rw-r--r--docs/source/conf.py2
-rw-r--r--docs/source/getting-started.rst141
-rw-r--r--docs/source/index.rst16
-rw-r--r--docs/source/license.rst4
-rw-r--r--poetry.lock34
-rw-r--r--pyproject.toml1
9 files changed, 193 insertions, 178 deletions
diff --git a/README.md b/README.md
deleted file mode 100644
index d36a709..0000000
--- a/README.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# Config File
-
-> Manage and manipulate your configuration files
-
-![Python Verisons](https://img.shields.io/pypi/pyversions/config-file.svg)
-[![Version](https://img.shields.io/pypi/v/config-file)](https://pypi.org/project/config-file/)
-[![Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://pypi.org/project/black/)
-[![Documentation Status](https://readthedocs.org/projects/config-file/badge/?version=latest)](https://config-file.readthedocs.io/en/latest/?badge=latest)
-[![Build Status](https://travis-ci.com/eugenetriguba/config_file.svg?branch=master)](https://travis-ci.com/eugenetriguba/config_file)
-[![Codecov](https://codecov.io/gh/eugenetriguba/config_file/graph/badge.svg)](https://codecov.io/gh/eugenetriguba/config_file)
-
-> This python package is currently in rapid development and is in a pre-alpha phase.
-> The API is liable to break until v1 so if you're going to use it, pinning the version
-> is recommended. All notable changes are kept track of in the changelog.
-
-Config File allows you to use the same simple API for manipulating INI, JSON,
-YAML, and TOML configuration files. For the time being, it only supports INI and
-JSON.
-
-## Installation
-```bash
-$ pip install config-file
-```
-
-## Example
-
-The `config_file` package exposes `ConfigFile`, `ParsingError`, and `BaseParser` to the public API.
-
-### Sample Configuration File
-
-`config.ini`
-```ini
-[calendar]
-today = monday
-start_week_on_sunday = false
-today_index = 0
-quarter_hours_passed = 0.25
-```
-
-### Create a ConfigFile
-```python
-from config_file import ConfigFile
-
-config = ConfigFile("~/.config/test/config.ini")
-```
-
-### Output your config file as a string
-```python
-config.stringify()
->>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 0\nquarter_hours_passed = 0.25\n\n'
-```
-
-### Retrieve values or sections
-A section.key format is used for retrieving and setting values.
-```python
-# Values from the config file are automatically parsed
-config.get("calendar.start_week_on_sunday")
->>> False
-
-# Unless you don't want them to be parsed
-config.get("calendar.start_week_on_sunday", parse_type=False)
->>> 'false'
-
-config.get("calendar")
->>> {'today': 'monday', 'start_week_on_sunday': False, 'today_index': 0, 'quarter_hours_passed': 0.25}
-```
-
-### Set values
-```python
-config.set("calendar.today_index", 20)
->>> True
-config.stringify()
->>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
-
-# If you specify a section that isn't in your config file, the section and the key are added for you.
-config.set("week.tuesday_index", 2)
->>> True
-config.stringify()
->>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n[week]\ntuesday_index = 2\n\n'
-```
-
-### Delete sections or key/value pairs.
-```python
-config.delete('week')
->>> True
-config.stringify()
->>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
-
-config.delete('calendar.today')
->>> True
-config.stringify()
->>> '[calendar]\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
-```
-
-
-### Check whether you have a particular section or key
-```python
-config.has('calendar')
->>> True
-
-config.has('week')
->>> False
-
-config.has('calendar.start_week_on_sunday')
->>> True
-```
-
-### Save when you're done
-Write the contents of the file back out. `set()` and `delete()` both modify the contents
-of the file and require a call to `save()` to write those changes back out.
-```python
-config.save()
->>> True
-```
-
-### Restore the file back to its original
-
-The current configuration file would be deleted and replaced by a copy of the original.
-By default, since our passed in config file was at path `~/.config/test/config.ini`,
-`restore_original()` will look for `~/.config/test/config.original.ini`.
-
-```python
-config.restore_original()
->>> True
-
-# But you can also specify the original config file explicitly.
-config.restore_original(original_file_path="~/some_other_directory/this_is_actually_the_original.ini")
->>> True
-```
-
-## Using your own parser
-
-You can still use config file, even if you don't use one of our supported configuration
-formats. The `ConfigFile` object swaps in the parser it needs based on the file format.
-However, the constructor takes in an optional `parser` argument that you can use to
-supply your own custom parser. The only requirement is that the parser must be a
-concrete implementation of `BaseParser`.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..525e95e
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,34 @@
+Config File
+===========
+
+ Manage and manipulate your configuration files
+
+|Python Verison| |Version| |Style| |Documentation Status| |Build Status| |Codecov|
+
+ This python package is currently in rapid development and is in a
+ pre-alpha phase. The API is liable to break until v1 so if you're
+ going to use it, pinning the version is recommended. All notable
+ changes are kept track of in the changelog.
+
+Config File allows you to use the same simple API for manipulating INI,
+JSON, YAML, and TOML configuration files. For the time being, it only
+supports INI and JSON.
+
+Installation
+------------
+
+.. code:: bash
+
+ $ pip install config-file
+
+.. |Python Verison| image:: https://img.shields.io/pypi/pyversions/config-file.svg
+.. |Version| image:: https://img.shields.io/pypi/v/config-file
+ :target: https://pypi.org/project/config-file/
+.. |Style| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+ :target: https://pypi.org/project/black/
+.. |Documentation Status| image:: https://readthedocs.org/projects/config-file/badge/?version=latest
+ :target: https://config-file.readthedocs.io/en/latest/?badge=latest
+.. |Build Status| image:: https://travis-ci.com/eugenetriguba/config_file.svg?branch=master
+ :target: https://travis-ci.com/eugenetriguba/config_file
+.. |Codecov| image:: https://codecov.io/gh/eugenetriguba/config_file/graph/badge.svg
+ :target: https://codecov.io/gh/eugenetriguba/config_file \ No newline at end of file
diff --git a/docs/source/api-reference.rst b/docs/source/api-reference.rst
new file mode 100644
index 0000000..4ea8c91
--- /dev/null
+++ b/docs/source/api-reference.rst
@@ -0,0 +1,2 @@
+API Reference
+============= \ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
index dae0782..60e5eb7 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -47,7 +47,7 @@ exclude_patterns = []
# 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"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
new file mode 100644
index 0000000..3ceb17e
--- /dev/null
+++ b/docs/source/getting-started.rst
@@ -0,0 +1,141 @@
+Getting Started
+===============
+
+Example
+-------
+
+The ``config_file`` package exposes ``ConfigFile``, ``ParsingError``,
+and ``BaseParser`` to the public API.
+
+Sample Configuration File
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``config.ini``
+
+.. code:: ini
+
+ [calendar]
+ today = monday
+ start_week_on_sunday = false
+ today_index = 0
+ quarter_hours_passed = 0.25
+
+Create a ConfigFile
+~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+ from config_file import ConfigFile
+
+ config = ConfigFile("~/.config/test/config.ini")
+
+Output your config file as a string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+ config.stringify()
+ >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 0\nquarter_hours_passed = 0.25\n\n'
+
+Retrieve values or sections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A section.key format is used for retrieving and setting values.
+
+.. code:: python
+
+ # Values from the config file are automatically parsed
+ config.get("calendar.start_week_on_sunday")
+ >>> False
+
+ # Unless you don't want them to be parsed
+ config.get("calendar.start_week_on_sunday", parse_type=False)
+ >>> 'false'
+
+ config.get("calendar")
+ >>> {'today': 'monday', 'start_week_on_sunday': False, 'today_index': 0, 'quarter_hours_passed': 0.25}
+
+Set values
+~~~~~~~~~~
+
+.. code:: python
+
+ config.set("calendar.today_index", 20)
+ >>> True
+ config.stringify()
+ >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
+
+ # If you specify a section that isn't in your config file, the section and the key are added for you.
+ config.set("week.tuesday_index", 2)
+ >>> True
+ config.stringify()
+ >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n[week]\ntuesday_index = 2\n\n'
+
+.. _delete-sections-or-keyvalue-pairs:
+
+Delete sections or key/value pairs.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+ config.delete('week')
+ >>> True
+ config.stringify()
+ >>> '[calendar]\ntoday = monday\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
+
+ config.delete('calendar.today')
+ >>> True
+ config.stringify()
+ >>> '[calendar]\nstart_week_on_sunday = false\ntoday_index = 20\nquarter_hours_passed = 0.25\n\n'
+
+Check whether you have a particular section or key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: python
+
+ config.has('calendar')
+ >>> True
+
+ config.has('week')
+ >>> False
+
+ config.has('calendar.start_week_on_sunday')
+ >>> True
+
+Save when you're done
+~~~~~~~~~~~~~~~~~~~~~
+
+Write the contents of the file back out. ``set()`` and ``delete()`` both
+modify the contents of the file and require a call to ``save()`` to
+write those changes back out.
+
+.. code:: python
+
+ config.save()
+ >>> True
+
+Restore the file back to its original
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The current configuration file would be deleted and replaced by a copy
+of the original. By default, since our passed in config file was at path
+``~/.config/test/config.ini``, ``restore_original()`` will look for
+``~/.config/test/config.original.ini``.
+
+.. code:: python
+
+ config.restore_original()
+ >>> True
+
+ # But you can also specify the original config file explicitly.
+ config.restore_original(original_file_path="~/some_other_directory/this_is_actually_the_original.ini")
+ >>> True
+
+Using your own parser
+---------------------
+
+You can still use config file, even if you don't use one of our supported
+configuration formats. The ``ConfigFile`` object swaps in the parser it needs
+based on the file format. However, the constructor takes in an optional
+parser argument that you can use to supply your own custom parser. The only
+requirement is that the parser must be a concrete implementation of ``BaseParser``. \ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e1670f5..f4baa8d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,15 +1,17 @@
-.. Config File documentation master file, created by
- sphinx-quickstart on Sun Feb 2 15:08:37 2020.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
+Config File Documentation
+=========================
-Welcome to Config File's documentation!
-=======================================
+Config File is a package that allows you to easily manipulate your configuration
+files whether they are in INI, JSON, YAML, TOML, or even XML.
+
+**Table of Contents:**
.. toctree::
:maxdepth: 2
- :caption: Contents:
+ getting-started
+ api-reference
+ license
Indices and tables
diff --git a/docs/source/license.rst b/docs/source/license.rst
new file mode 100644
index 0000000..01f3963
--- /dev/null
+++ b/docs/source/license.rst
@@ -0,0 +1,4 @@
+License
+=======
+
+.. include:: ../../LICENSE \ No newline at end of file
diff --git a/poetry.lock b/poetry.lock
index 3220b9d..cdc96fc 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -159,17 +159,6 @@ version = "0.4.3"
[[package]]
category = "dev"
-description = "Python parser for the CommonMark Markdown spec"
-name = "commonmark"
-optional = false
-python-versions = "*"
-version = "0.9.1"
-
-[package.extras]
-test = ["flake8 (3.7.8)", "hypothesis (3.55.3)"]
-
-[[package]]
-category = "dev"
description = "Code coverage measurement for Python"
name = "coverage"
optional = false
@@ -476,19 +465,6 @@ python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
version = "5.3"
[[package]]
-category = "dev"
-description = "A docutils-compatibility bridge to CommonMark, enabling you to write CommonMark inside of Docutils & Sphinx projects."
-name = "recommonmark"
-optional = false
-python-versions = "*"
-version = "0.6.0"
-
-[package.dependencies]
-commonmark = ">=0.8.1"
-docutils = ">=0.11"
-sphinx = ">=1.3.1"
-
-[[package]]
category = "main"
description = "Python HTTP for Humans."
name = "requests"
@@ -690,7 +666,7 @@ more-itertools = "*"
docs = ["sphinx", "jaraco.packaging (>=3.2)", "rst.linker (>=1.9)"]
[metadata]
-content-hash = "6f9e4a7f9772a53e1df51e4a2adacfd3a1efacf42a8b0468a48b7b2fa7ebffcc"
+content-hash = "41f7048a3693045fee50d3fbd0701ef5c0cec5b0577a42ea294193e5b1bbf834"
python-versions = "^3.6"
[metadata.files]
@@ -757,10 +733,6 @@ colorama = [
{file = "colorama-0.4.3-py2.py3-none-any.whl", hash = "sha256:7d73d2a99753107a36ac6b455ee49046802e59d9d076ef8e47b61499fa29afff"},
{file = "colorama-0.4.3.tar.gz", hash = "sha256:e96da0d330793e2cb9485e9ddfd918d456036c7149416295932478192f4436a1"},
]
-commonmark = [
- {file = "commonmark-0.9.1-py2.py3-none-any.whl", hash = "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9"},
- {file = "commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60"},
-]
coverage = [
{file = "coverage-5.0.3-cp27-cp27m-macosx_10_12_x86_64.whl", hash = "sha256:cc1109f54a14d940b8512ee9f1c3975c181bbb200306c6d8b87d93376538782f"},
{file = "coverage-5.0.3-cp27-cp27m-macosx_10_13_intel.whl", hash = "sha256:be18f4ae5a9e46edae3f329de2191747966a34a3d93046dbdf897319923923bc"},
@@ -935,10 +907,6 @@ pyyaml = [
{file = "PyYAML-5.3-cp38-cp38-win_amd64.whl", hash = "sha256:cb1f2f5e426dc9f07a7681419fe39cee823bb74f723f36f70399123f439e9b20"},
{file = "PyYAML-5.3.tar.gz", hash = "sha256:e9f45bd5b92c7974e59bcd2dcc8631a6b6cc380a904725fce7bc08872e691615"},
]
-recommonmark = [
- {file = "recommonmark-0.6.0-py2.py3-none-any.whl", hash = "sha256:2ec4207a574289355d5b6ae4ae4abb29043346ca12cdd5f07d374dc5987d2852"},
- {file = "recommonmark-0.6.0.tar.gz", hash = "sha256:29cd4faeb6c5268c633634f2d69aef9431e0f4d347f90659fd0aab20e541efeb"},
-]
requests = [
{file = "requests-2.22.0-py2.py3-none-any.whl", hash = "sha256:9cf5292fcd0f598c671cfc1e0d7d1a7f13bb8085e9a590f48c010551dc6c4b31"},
{file = "requests-2.22.0.tar.gz", hash = "sha256:11e007a8a2aa0323f5a921e9e6a2d7e4e67d9877e85773fba9ba6419025cbeb4"},
diff --git a/pyproject.toml b/pyproject.toml
index 3b5991a..9eb0f6a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -21,6 +21,7 @@ python = "^3.6"
toml = "^0.10.0"
pyyaml = "^5.2"
nested-lookup = "^0.2.19"
+sphinx_rtd_theme = "^0.4.3"
[tool.poetry.dev-dependencies]
pre-commit = "^1.20"