Docs (#38)

Add ReadTheDocs

.gitignore

@@ -5,3 +5,4 @@ dist/
 build/
 .env
 *.log
+docs/html/

.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+
+sphinx:
+  configuration: docs/source/conf.py
+  fail_on_warning: true
+
+formats:
+  - pdf

.vscode/tasks.json

@@ -36,6 +36,28 @@
         "panel": "shared"
       },
       "problemMatcher": []
+    },
+    {
+      "label": "sphinx",
+      "type": "shell",
+      "command": "python -m sphinx -T -W --keep-going -b html -d build/doctrees -D language=en docs/source docs/html",
+      "group": "test",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "http server",
+      "type": "shell",
+      "command": "python -m http.server -d docs/html",
+      "group": "test",
+      "presentation": {
+        "reveal": "always",
+        "panel": "shared"
+      },
+      "problemMatcher": []
     }
   ]
 }

README.rst

@@ -0,0 +1,30 @@
+Python SAP Commissions®
+=======================
+
+An Asynchronous Python client to communicate with SAP Commissions®.
+
+If you like this project, please consider to `BuyMeACoffee <https://www.buymeacoffee.com/niro1987>`_.
+
+.. image:: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
+    :alt: BuyMeACoffee
+    :target: https://www.buymeacoffee.com/niro1987
+
+Documentation
+-------------
+
+Read the full documentation on [Read the Docs](https://python-sapcommissions.readthedocs.io/)
+
+REST API
+--------
+
+This project mimics the usage of the SAP Commissions REST API. Visit
+:code:`https://{TENANT}.callidusondemand.com/APIDocument` to read the full specification, replacing :code:`TENANT` with your
+tenant-id.
+
+Legal Disclamer
+---------------
+
+This software is designed for use with SAP Commissions®. It is not affiliated with SAP® and the developers
+take no legal responsibility for the functionality or security of your Commissions environment.
+
+SAP Commissions is a registered trademark of SAP SE or its affiliates in Germany and in other countries.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx==7.4.7
+sphinx-rtd-theme==2.0.0
+myst-parser==4.0.0

docs/source/cli.rst

@@ -0,0 +1,197 @@
+Command-Line Interface
+======================
+
+Usage
+-----
+
+This project includes some command-line-interface commands,
+to install the required dependencies, install them with pip:
+
+.. code-block:: console
+
+    (.venv) $ pip install python-sapcommissions[cli]
+
+Options:
+    - ``--tenant {TENANT}``: **Required**
+        Tenant to connect to, for example 'CALD-DEV'.
+    - ``--username {USERNAME}``: **Required**
+        Username for authentication.
+    - ``--password {PASSWORD}``: **Required**
+        Password for authentication.
+    - ``--no-ssl``: *Optional*
+        Disable SSL validation.
+    - ``--logfile {PATH}``: *Optional*
+        Enable logging to a file.
+    - ``-v``: *Optional*
+        Increase log verbosity.
+
+To list all available options and commands:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapcommissions --help
+
+.. code-block:: console
+
+    Usage: python -m sapcommissions [OPTIONS] COMMAND [ARGS]...
+
+    Command-line interface for Python SAP Commissions.
+
+    You may provide parameters by setting environment variables
+    prefixed with 'SAP_' or by passing them as options.
+    For example: `export SAP_TENANT=CALD-DEV` is equivalent
+    to passing `--tenant CALD-DEV`
+
+    Options:
+    -t, --tenant TEXT    Tenant to connect to, for example 'CALD-DEV'.
+    -u, --username TEXT  Username for authentication.
+    -p, --password TEXT  Password for authentication.
+    --no-ssl             Disable SSL validation.
+    -l, --logfile FILE   Enable logging to a file.
+    -v                   Increase logging verbosity.
+    --help               Show this message and exit.
+
+    Commands:
+    calendars  List all calendars.
+    deploy     Deploy rule elements from a directory to the tenant.
+    export     Export Resource to a file.
+    periods    List all periods for a calendar.
+
+Each command has it's own options, to list all options, append ``--help`` to the command.
+
+Calendars
+---------
+
+List all calendars:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapcommissions \
+        --tenant {TENANT} \
+        --username {USERNAME} \
+        --password {PASSWORD} \
+        calendars
+
+Periods
+-------
+
+Options:
+    - ``--calendar {CALENDAR}`` **Required**
+        The calendar name to list periods for.
+    - ``--period {PERIOD}`` *Optional*
+        Name of the Period to search. Allows wildcard like ``*2024*``.
+
+List all periods for a calendar:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapcommissions \
+        --tenant {TENANT} \
+        --username {USERNAME} \
+        --password {PASSWORD} \
+        periods --calendar {CALENDAR}
+
+Deploy
+------
+
+Deploy exported Plan Data and Global Values from a
+directory to the tenant.
+
+Plan data ``*.xml`` is imported with an import pipeline job.
+Global Values ``*.txt`` are imported with their respective :ref:`model:data type`.
+
+To correctly identify the :ref:`model:data type`, files have to follow a specific
+naming convention:
+
+    - Event Type.txt
+    - Credit Type.txt
+    - Earning Group.txt
+    - Earning Code.txt
+    - Fixed Value Type.txt
+    - Reason Code.txt
+
+Additionally you can control the order of processing by prefixing the filenames.
+For example:
+
+    - 01 Event Type.txt
+    - 02 Credit Type.txt
+    - 03 Plan.XML
+
+.. tip::
+    Enable logging to catch import errors.
+    See ``--logfile log.txt`` in the below example.
+
+Arguments:
+    - ``PATH``: **Required**
+        The path to the directory to be processed.
+
+.. code-block:: console
+
+    (.venv) $ python -m sapcommissions \
+        --tenant {TENANT} \
+        --username {USERNAME} \
+        --password {PASSWORD} \
+        --logfile log.txt \
+        deploy ./deploy
+
+
+Export
+------
+
+Export Credits, Measurements, Incentives, Commissions, Deposits and Payments to a file
+in the same way you would using the respective UI workspaces.
+
+Options:
+    - ``--calendar {CALENDAR}`` *Optional*
+        Apply :py:class:`Calendar <sapcommissions.model.resource.Calendar>` filter on the exported data.
+    - ``--period {PERIOD}`` *Optional*
+        Apply :py:class:`Period <sapcommissions.model.resource.Period>` filter on the exported data.
+        Requires ``--calendar`` to be provided.
+    - ``--filters {FILTER_TEXT}`` *Optional*
+        Apply :py:class:`Period <sapcommissions.model.resource.Period>` filter on the exported data.
+        Can be applied more then once.
+
+.. tip::
+
+    Refer to the :ref:`API Documentation <index:rest api>` to understand the filter mechanism.
+
+Arguments:
+    - ``RESOURCE`` **Required**
+        The resource to load into a file.
+        One of ``{CREDITS|MEASUREMENTS|INCENTIVES|COMMISSIONS|DEPOSITS|PAYMENTS}``
+    - ``PATH`` **Required**
+        Path of the file to write to.
+
+.. note::
+
+    Exporting a large number of records will lead to poor performance. It is strngly
+    recommended to stay below 100.000 records.
+
+.. tip::
+    Enable logging to catch import errors.
+    See ``--logfile log.txt`` in the below examples.
+
+Export credits to a file:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapcommissions \
+        --tenant {TENANT} \
+        --username {USERNAME} \
+        --password {PASSWORD} \
+        --logfile log.txt \
+        export CREDITS credits.txt \
+        --calendar {CALENDAR} \
+        --period {PERIOD}
+
+Export payments above € 100.000,-:
+
+.. code-block:: console
+
+    (.venv) $ python -m sapcommissions \
+        --tenant {TENANT} \
+        --username {USERNAME} \
+        --password {PASSWORD} \
+        --logfile log.txt \
+        export PAYMENTS payments.txt \
+        --filter "payment ge '100000 EUR'"

docs/source/client.rst

@@ -0,0 +1,14 @@
+Client
+======
+
+.. autosummary:: sapcommissions.client
+
+.. hint::
+    See :ref:`usage:examples`
+
+.. automodule:: sapcommissions.client
+
+    .. autoclass:: CommissionsClient
+        :members:
+        :private-members: _request
+        :member-order: bysource