From 88ed4e2ebe6371c6584f72d9e1d26b2194fbb119 Mon Sep 17 00:00:00 2001 From: "Pollerspoeck Thomas (XC-CT/ECA3)" Date: Wed, 14 Dec 2022 18:13:28 +0100 Subject: [PATCH] intermediate: readme and documentation maintenance --- README.md | 67 ++++---- README.rst | 56 ++++--- packagedoc/additional_docs/Description.rst | 164 ++++++++++---------- packagedoc/additional_docs/Description.tex | 1 + packagedoc/additional_docs/Introduction.rst | 28 ++-- packagedoc/additional_docs/Introduction.tex | 42 +++++ 6 files changed, 215 insertions(+), 143 deletions(-) create mode 100644 packagedoc/additional_docs/Description.tex create mode 100644 packagedoc/additional_docs/Introduction.tex diff --git a/README.md b/README.md index e3fbbd92..f4f94650 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,51 @@ -> Licensed under the Apache License, Version 2.0 (the \"License\"); you -> may not use this file except in compliance with the License. You may -> obtain a copy of the License at -> -> -> -> Unless required by applicable law or agreed to in writing, software -> distributed under the License is distributed on an \"AS IS\" BASIS, -> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -> implied. See the License for the specific language governing -> permissions and limitations under the License. - -# Json Preprocessor\'s Package Description +# Package description for JsonPreprocessor ## Getting Started -The JsonPreprocessor is a Python3 package which allows programmers to -handle additional features in json files such as +The JsonPreprocessor is a Python3 package which provides additional +features for JSON files. -- add comments -- import other json files -- overwrite already existing parameters with new values +These are: -These json files will be handled by the JsonPreprocessor which returns -as result a dictionary object of the deserialized data. +- (nested) import of other json files. +- overwrite already existing parameters with new values from later + loaded json files. +- accept `True`, `False` and `None` as data types. +- support for comments. + +The JsonPreprocessor returns as result a dictionary object of the +deserialized preprocessed data. ## How to install -Firstly, clone **python-jsonpreprocessor** repository to your machine. +**JsonPreprocessor** can be installed in two different ways. + +1. Installation via PyPi (recommended for users) + + ``` + pip install JsonPreprocessor + ``` + + [JsonPreprocessor in + PyPi](https://pypi.org/project/JsonPreprocessor/) + +2. Installation via GitHub (recommended for developers) + + Clone the **python-jsonpreprocessor** repository to your machine. + + ``` + git clone https://github.com/test-fullautomation/python-jsonpreprocessor.git + ``` -Then go to python-jsonpreprocessor, using the 2 common commands below to -build or install this package: + [JsonPreprocessor in + GitHub](https://github.com/test-fullautomation/python-jsonpreprocessor) -``` -setup.py build will build the package underneath 'build/' -setup.py install will install the package -``` + Use the following command to install **JsonPreprocessor**: -After the build processes is completed, the package is located in -\'build/\', and the generated package documentation is located in -\'doc/\_build/\'. + ``` + cd python-jsonpreprocessor + setup.py install + ``` ## Package Documentation diff --git a/README.rst b/README.rst index 488d2017..9ff808ae 100644 --- a/README.rst +++ b/README.rst @@ -1,47 +1,65 @@ .. Copyright 2020-2022 Robert Bosch GmbH - Licensed under the Apache License, Version 2.0 (the "License"); +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 +.. http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software +.. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -Json Preprocessor's Package Description -======================================= +Package description for JsonPreprocessor +======================================== Getting Started --------------- -The JsonPreprocessor is a Python3 package which allows programmers to handle -additional features in json files such as +The JsonPreprocessor is a Python3 package which provides additional features for +JSON files. -* add comments -* import other json files -* overwrite already existing parameters with new values +These are: -These json files will be handled by the JsonPreprocessor which returns as result -a dictionary object of the deserialized data. +* (nested) import of other json files. +* overwrite already existing parameters with new values from later loaded json files. +* accept ``True``, ``False`` and ``None`` as data types. +* support for comments. + +The JsonPreprocessor returns as result a dictionary object of the deserialized +preprocessed data. How to install -------------- -Firstly, clone **python-jsonpreprocessor** repository to your machine. +**JsonPreprocessor** can be installed in two different ways. + +1. Installation via PyPi (recommended for users) + + .. code:: + + pip install JsonPreprocessor + + `JsonPreprocessor in PyPi `_ + +2. Installation via GitHub (recommended for developers) + + Clone the **python-jsonpreprocessor** repository to your machine. + + .. code:: + + git clone https://github.com/test-fullautomation/python-jsonpreprocessor.git -Then go to python-jsonpreprocessor, using the 2 common commands below to build or install this package: + `JsonPreprocessor in GitHub `_ -.. code-block:: + Use the following command to install **JsonPreprocessor**: - setup.py build will build the package underneath 'build/' - setup.py install will install the package + .. code:: -After the build processes is completed, the package is located in 'build/', and the generated -package documentation is located in 'doc/_build/'. + cd python-jsonpreprocessor + setup.py install Package Documentation diff --git a/packagedoc/additional_docs/Description.rst b/packagedoc/additional_docs/Description.rst index c61474a5..edaed36e 100644 --- a/packagedoc/additional_docs/Description.rst +++ b/packagedoc/additional_docs/Description.rst @@ -15,36 +15,42 @@ How to install -------------- -Firstly, clone `python-jsonpreprocessor `_ -repository to your machine. +**JsonPreprocessor** can be installed in two different ways. -Then open the folder in which you have cloned the repository python-jsonpreprocessor, following the commands -below to build or install this package: +1. Installation via PyPi (recommended for users) -.. code:: + .. code:: - setup.py build will build the package underneath 'build/' - setup.py install will install the package + pip install JsonPreprocessor -After the build processes is completed, the package is located in 'build/', and the generated package -documentation is located in **/JsonPreprocessor**. + `JsonPreprocessor in PyPi `_ -We can use ``--help`` to discover the options for ``build`` command, example: +2. Installation via GitHub (recommended for developers) -.. code:: + Clone the **python-jsonpreprocessor** repository to your machine. + + .. code:: + + git clone https://github.com/test-fullautomation/python-jsonpreprocessor.git - setup.py build will build the package underneath 'build/' - setup.py install will install the package + `JsonPreprocessor in GitHub `_ -Features --------- + Use the following command to install **JsonPreprocessor**: -Basic Json format + .. code:: + + cd python-jsonpreprocessor + setup.py install + +JsonPreprocessor Features +------------------------- + +Basic JSON format ~~~~~~~~~~~~~~~~~ -Users can use JsonPreprocessor to handle the json file with its original format. +Users can use JsonPreprocessor to handle any JSON file with its format as per JSON specification. -**Example:** +**Example**: .. code:: @@ -67,13 +73,11 @@ Users can use JsonPreprocessor to handle the json file with its original format. "device" : "device_name" } -Adding the comments +Adding comments ~~~~~~~~~~~~~~~~~~~ -Often large projects require a lot of configuration parameters. So adding comments to json files is -useful in case of more and more content is added, e.g. because of a json file has to hold a huge number -of configuration parameters for different features. Comments can be used here to clarify the meaning of -these parameters or the differences between them. +Often large projects require large JSON files. Comments can be used here to clarify the meaning of +parameters or the differences between them. Every line starting with **"//"**, is commented out. Therefore a comment is valid for singles lines only. @@ -84,10 +88,10 @@ Comment out a block of several lines with only one start and one end comment str .. code:: //***************************************************************************** - // Author: ROBFW-AIO Team + // Author: Author_of_the_file // - // This file defines all common global parameters and will be included to all - // test config files + // This file defines some paramters and will be included to other + // JSON files. //***************************************************************************** { "Project": "name_of_prject", @@ -110,28 +114,31 @@ Comment out a block of several lines with only one start and one end comment str "device" : "device_name" } -Imports other json files +Import other JSON files ~~~~~~~~~~~~~~~~~~~~~~~~ -This import feature enables developers to take over the content of other json files into the -current json file. A json file that is imported into another json file, can contain imports also -(allows nested imports). +The import feature enables users to take over the content of another JSON file(s) into the +current JSON file. A JSON file that is imported into another JSON file, can contain imports also +(nested imports). -A possible usecase for nested imports is to handle configuration parameters of different variants -of a feature or a component within a bunch of several smaller files, instead of putting all parameter -into only one large json file. +A possible usecase for nested imports is to handle configuration parameters in a hierarchical way. +Parameters which belong together are defined in a separate JSON file and at the end inported to +a JSON file which brings parameters together. + +This allows you to build up JSON files which are hierarchichally loaded, starting with +a default value which you overwrite with a later loaded JSON file. **Example:** -Suppose we have the json file ``params_global.json`` with the content: +Suppose we have the JSON file ``params_global.json`` with the content: .. code:: //***************************************************************************** - // Author: ROBFW-AIO Team + // Author: Author_of_the_file // // This file defines all common global parameters and will be included to all - // test config files + // configuration files //***************************************************************************** // // This is to distinguish the different types of resets @@ -145,15 +152,15 @@ Suppose we have the json file ``params_global.json`` with the content: } } -And other json file ``preprocessor_definitions.json`` with content: +And another JSON file ``preprocessor_definitions.json`` with the following content: .. code:: //***************************************************************************** - // Author: ROBFW-AIO Team + // Author: Author_of_the_file // // This file defines all common global parameters and will be included to all - // test config files + // configuration files //***************************************************************************** { "import_param_3" : "value_3", @@ -167,18 +174,18 @@ And other json file ``preprocessor_definitions.json`` with content: } } -Then we can import these 2 files above to the json file ``config.json`` with the [import] statement: +Now we can import the two files above into the JSON file ``config.json`` with the **``[import]``** statement: .. code:: //***************************************************************************** - // Author: ROBFW-AIO Team + // Author: Author_of_the_file // // This file defines all common global parameters and will be included to all - // test config files + // configuration files //***************************************************************************** { - "Project": "name_of_prject", + "Project": "name_of_project", "version": { "major": "0", "minor": "1", @@ -186,23 +193,23 @@ Then we can import these 2 files above to the json file ``config.json`` with the }, "params": { "global": { - "[import]": "/params_global.json" + "[import]": "/params_global.json" } }, "preprocessor": { "definitions": { - "[import]": "/preprocessor_definitions.json" + "[import]": "/preprocessor_definitions.json" } }, "device" : "device_name" } -After all imports are resolved by the JsonPreprocessor, this is the resulting of data structure: +After all imports are resolved by the JsonPreprocessor, this is the resulting data structure: .. code:: { - "Project": "name_of_prject", + "Project": "name_of_project", "version": { "major": "0", "minor": "1", @@ -229,29 +236,24 @@ After all imports are resolved by the JsonPreprocessor, this is the resulting of "device" : "device_name" } - Add new or overwrites existing parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Add new or overwrites existing parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This JsonPreprocessor package also provides developers ability to add new as well as overwrite +JsonPreprocessor provides users the powerful possibility to add new as well as overwrite existing parameters. Developers can update parameters which are already declared and add new -parameters or new element into existing parameters. The below example will show the way to do -these features. - -In case we have many different variants, and each variant requires a different value assigned -to the parameter, users can use this feature to add new parameters and update new values for -existing parameters of existing configuation object. +parameters or new elements into existing parameters. **Example:** -Suppose we have the json file ``params_global.json`` with the content: +Suppose we have the JSON file ``params_global.json`` with the content: .. code:: //***************************************************************************** - // Author: ROBFW-AIO Team + // Author: Author_of_the_file // // This file defines all common global parameters and will be included to all - // test config files + // configuration files //***************************************************************************** // // This is to distinguish the different types of resets @@ -265,7 +267,7 @@ Suppose we have the json file ``params_global.json`` with the content: } } -Then we import ``params_global.json`` to json file ``config.json`` with content: +Then we import ``params_global.json`` to JSON file ``config.json`` with content: .. code:: @@ -278,7 +280,7 @@ Then we import ``params_global.json`` to json file ``config.json`` with content: }, "params": { "global": { - "[import]": "/params_global.json" + "[import]": "/params_global.json" } }, "device" : "device_name", @@ -287,8 +289,8 @@ Then we import ``params_global.json`` to json file ``config.json`` with content: "${version}['patch']": "2", // Add new parameters "new_param": { - "abc": 9, - "xyz": "new param" + "abc": 9, + "xyz": "new param" }, "${params}['global']['import_structure_1']['new_structure_param']": "new_structure_value" } @@ -310,28 +312,28 @@ After all imports are resolved by the JsonPreprocessor, this is the resulting of "import_param_2" : "value_2", "import_structure_1": { "general": "general", - "new_structure_param": "new_structure_value" + "new_structure_param": "new_structure_value" } } }, "device" : "device_name", "new_param": { - "abc": 9, - "xyz": "new param" + "abc": 9, + "xyz": "new param" } } -Using defined parameters -~~~~~~~~~~~~~~~~~~~~~~~~ +Using already defined parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -With JsonPreprocessor package, users can also use the defined parameters in Json file. The value of -the defined parameter could be called with syntax ``${}`` +JsonPreprocessor allows you to use the already defined parameters. You can +refer to any already defined parameter by means of ``${}``-syntax. **Example:** -Suppose we have the json file ``config.json`` with the content: +Suppose we have the JSON file ``config.json`` with the content: -.. code:: +.. code::json { "Project": "name_of_prject", @@ -353,7 +355,7 @@ Suppose we have the json file ``config.json`` with the content: "definitions": { "import_param_3" : "value_3", "import_param_4" : "value_4", - "ABC": "param_ABC", + "ABC": "param_ABC", "import_structure_1": { "general": "general" } @@ -365,7 +367,7 @@ Suppose we have the json file ``config.json`` with the content: "${params}['global']['import_param_1']": ${preprocessor}['definitions']['import_param_4'] } -After all imports are resolved by the JsonPreprocessor, this is the resulting of data structure: +After all imports are resolved by JsonPreprocessor, this is the resulting data structure: .. code:: @@ -383,14 +385,14 @@ After all imports are resolved by the JsonPreprocessor, this is the resulting of "import_structure_1": { "general": "general" }, - "param_ABC": True + "param_ABC": True } }, "preprocessor": { "definitions": { "import_param_3" : "value_3", "import_param_4" : "value_4", - "ABC": "param_ABC", + "ABC": "param_ABC", "import_structure_1": { "general": "general" } @@ -399,14 +401,14 @@ After all imports are resolved by the JsonPreprocessor, this is the resulting of "TargetName" : "device_name" } -Accepted ``True``, ``False``, and ``None`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Python-like ``True``, ``False``, and ``None`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some keywords are different between Json and Python syntax: +Some keywords are different between JSON and Python syntax: -* Json syntax: **``true``**, **``false``**, **``null``** +* JSON syntax: **``true``**, **``false``**, **``null``** * Python syntax: **``True``**, **``False``**, **``None``** -To facilitate the usage of configuration files in Json format, both ways of syntax are accepted. +JsonPreprocessor enables both ways of syntax. diff --git a/packagedoc/additional_docs/Description.tex b/packagedoc/additional_docs/Description.tex new file mode 100644 index 00000000..1b3ff1ef --- /dev/null +++ b/packagedoc/additional_docs/Description.tex @@ -0,0 +1 @@ +Description \ No newline at end of file diff --git a/packagedoc/additional_docs/Introduction.rst b/packagedoc/additional_docs/Introduction.rst index 1005b2ac..b46fbef4 100644 --- a/packagedoc/additional_docs/Introduction.rst +++ b/packagedoc/additional_docs/Introduction.rst @@ -15,23 +15,25 @@ Json Preprocessor documentation =============================== -**This is the documentation for Python JsonPreprocessor** +The JsonPreprocessor is a Python3 package which provides additional features for +JSON files. -Json is a format used to represent data and becomes the universal standard of data -exchange. Today many software projects are using configuration file in Json format. -For a big or a complex project there is a need to have some enhanced format in Json -file such as adding the comments, importing other Json files, etc. +These are: -Based on that needs, we develop JsonPreprocessor package: +* ability to (nested) import other JSON files. Users can create separate JSON files + and then import them to another JSON file. -* Gives the possibility to comment out parts of the content. This feature can be used to - explain the meaning of the parameters defined inside the configuration files. +* allow users using already defined parameters with ``${parameter}``-syntax in JSON files. -* Has ability to import other Json files. This feature can be applied for complex project, - users can create separated Json files then importing them to other Json file. +* overwrite already existing parameters with new values from later loaded json files. -* Allows users using the defined parameter in Json file. +* accept Python like ``True``, ``False`` and ``None`` + in JSON syntax. -* Accepts **``True``**, **``False``**, and **``None``** in Json syntax +* provide the possibility to comment out parts of the JSON file content. This + feature can be used to explain the meaning of parameters defined + inside the JSON files. + +The JsonPreprocessor returns as result a dictionary object of the deserialized +preprocessed data. - .. image:: ./pictures/python3-jsonpreprocessor.png diff --git a/packagedoc/additional_docs/Introduction.tex b/packagedoc/additional_docs/Introduction.tex new file mode 100644 index 00000000..4d5f1cd0 --- /dev/null +++ b/packagedoc/additional_docs/Introduction.tex @@ -0,0 +1,42 @@ +% -------------------------------------------------------------------------------------------------------------- +% +% Copyright 2020-2022 Robert Bosch GmbH + +% Licensed under the Apache License, Version 2.0 (the "License"); +% you may not use this file except in compliance with the License. +% You may obtain a copy of the License at + +% http://www.apache.org/licenses/LICENSE-2.0 + +% Unless required by applicable law or agreed to in writing, software +% distributed under the License is distributed on an "AS IS" BASIS, +% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +% See the License for the specific language governing permissions and +% limitations under the License. +% +% -------------------------------------------------------------------------------------------------------------- + +The JsonPreprocessor is a Python3 package which provides additional features for +JSON files. + +The sources of the JsonPreprocessor are available in \href{https://github.com/test-fullautomation/python-jsonpreprocessor}{GitHub}. + +These are: +\begin{enumerate} +\item \texttt{import}\\ + ability to (nested) import other JSON files. Users can create separate JSON files and then import + them to another JSON file. +\item \texttt{\$\{parameter\}-syntax}\\ + allows users to use already defined parameters by means of \pcode{\$\{parameter\}}-syntax in JSON files. +\item \texttt{overwrite}\\ + overwrite already existing parameters with new values from later loaded JSON files. +\item \texttt{Python-like syntax}\\ + accept Python like ``True``, ``False`` and ``None`` in JSON files. +\item \texttt{comments}\\ + provide the possibility to comment out parts of the JSON file content for documentation purposes. +\end{enumerate} + +The JsonPreprocessor returns as result a dictionary object of the deserialized +preprocessed JSON data. + +