aboutsummaryrefslogtreecommitdiffstats
path: root/docs
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 /docs
parentAdd sphinx-quickstart (diff)
downloadconfig-file-effe00be8f1413ed57e3dac2ff73e012696831a7.zip
Move some of the docs over to sphinx on a RTD theme
Diffstat (limited to 'docs')
-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
5 files changed, 157 insertions, 8 deletions
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