From effe00be8f1413ed57e3dac2ff73e012696831a7 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sun, 2 Feb 2020 16:39:48 -0600 Subject: Move some of the docs over to sphinx on a RTD theme --- README.md | 137 -------------------------------------- README.rst | 34 ++++++++++ docs/source/api-reference.rst | 2 + docs/source/conf.py | 2 +- docs/source/getting-started.rst | 141 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 16 +++-- docs/source/license.rst | 4 ++ poetry.lock | 34 +--------- pyproject.toml | 1 + 9 files changed, 193 insertions(+), 178 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/source/api-reference.rst create mode 100644 docs/source/getting-started.rst create mode 100644 docs/source/license.rst 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 @@ -157,17 +157,6 @@ optional = false python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" 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" @@ -475,19 +464,6 @@ optional = false 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." @@ -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" -- cgit v1.2.3