diff options
| author | Eugene Triguba <eugenetriguba@gmail.com> | 2020-02-02 16:39:48 -0600 |
|---|---|---|
| committer | Eugene Triguba <eugenetriguba@gmail.com> | 2020-02-02 16:39:48 -0600 |
| commit | effe00be8f1413ed57e3dac2ff73e012696831a7 (patch) | |
| tree | 488849998fd0e6bd6abc1251d02891bd039cd448 /docs/source | |
| parent | Add sphinx-quickstart (diff) | |
| download | config-file-effe00be8f1413ed57e3dac2ff73e012696831a7.zip | |
Move some of the docs over to sphinx on a RTD theme
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/api-reference.rst | 2 | ||||
| -rw-r--r-- | docs/source/conf.py | 2 | ||||
| -rw-r--r-- | docs/source/getting-started.rst | 141 | ||||
| -rw-r--r-- | docs/source/index.rst | 16 | ||||
| -rw-r--r-- | docs/source/license.rst | 4 |
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 |