Merge pull request #15 from nassauwinter/initial_docs

Initial documentation on readthedocs.io

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

Pipfile

@@ -14,3 +14,6 @@ pylint = "*"
 build = "*"
 twine = "*"
 tox-gh-actions = "*"
+sphinx = "*"
+sphinx-rtd-theme = "*"
+myst-parser = "*"

README.md

@@ -5,7 +5,11 @@
 ![PyPI](https://img.shields.io/pypi/v/zephyr-python-api)
 ![PyPI - License](https://img.shields.io/pypi/l/zephyr-python-api)
 ### Project description
-This is a set of wrappers for Zephyr Scale (TM4J) REST API. This means you can interact with Zephyr Scale without GUI, access it with python code and create automation scripts for your every day interactions.
+This is a set of wrappers for Zephyr Scale (TM4J) REST API. 
+This means you can interact with Zephyr Scale without GUI, access it with python code and create 
+automation scripts for your every day interactions.
+
+For more detailed information please see [the project's documentation](https://zephyr-python-api.readthedocs.io/en/main/index.html).
 
 To be done:
 * More usage examples
@@ -25,7 +29,7 @@ Zephyr Cloud auth:
 ```python
 from zephyr import ZephyrScale
 
-zscale = ZephyrScale(token=<your_token>)
+zscale = ZephyrScale(token="<your_token>")
 ```
 
 Zephyr Server (TM4J) auth:
@@ -41,7 +45,7 @@ auth = {"username": "<your_login>", "password": "<your_password>"}
 # or even session cookie dict
 auth = {"cookies": "<session_cookie_dict>"}
 
-zscale = ZephyrScale.server_api(base_url=<your_base_url>, **auth)
+zscale = ZephyrScale.server_api(base_url="<your_base_url>", **auth)
 ```
 
 Then it is possible to interact with api wrappers:
@@ -58,11 +62,6 @@ test_case = zapi.test_cases.get_test_case("<test_case_id>")
 creation_result = zapi.test_cases.create_test_case("<project_key>", "test_case_name")
 ```
 
-### Troubleshooting
-
-For troubleshooting see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
-
-
 ### License
 
 This library is licensed under the Apache 2.0 License.

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
+
+%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.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%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,77 @@
+#
+# These requirements were autogenerated by pipenv
+# To regenerate from the project's Pipfile, run:
+#
+#    pipenv lock --requirements --dev-only
+#
+
+-i https://pypi.org/simple
+alabaster==0.7.13; python_version >= '3.6'
+astroid==2.15.6; python_full_version >= '3.7.2'
+babel==2.12.1; python_version >= '3.7'
+bleach==6.0.0; python_version >= '3.7'
+build==0.10.0
+cachetools==5.3.1; python_version >= '3.7'
+certifi==2023.5.7; python_version >= '3.6'
+chardet==5.1.0; python_version >= '3.7'
+charset-normalizer==3.2.0; python_full_version >= '3.7.0'
+colorama==0.4.6; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5, 3.6'
+dill==0.3.6; python_version < '3.11'
+distlib==0.3.6
+docutils==0.18.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'
+exceptiongroup==1.1.2; python_version < '3.11'
+filelock==3.12.2; python_version >= '3.7'
+idna==3.4; python_version >= '3.5'
+imagesize==1.4.1; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+importlib-metadata==6.8.0; python_version < '3.12'
+iniconfig==2.0.0; python_version >= '3.7'
+isort==5.12.0; python_version >= '3.8'
+jaraco.classes==3.3.0; python_version >= '3.8'
+jinja2==3.1.2; python_version >= '3.7'
+keyring==24.2.0; python_version >= '3.8'
+lazy-object-proxy==1.9.0; python_version >= '3.7'
+markdown-it-py==3.0.0; python_version >= '3.8'
+markupsafe==2.1.3; python_version >= '3.7'
+mccabe==0.7.0; python_version >= '3.6'
+mdit-py-plugins==0.4.0; python_version >= '3.8'
+mdurl==0.1.2; python_version >= '3.7'
+more-itertools==9.1.0; python_version >= '3.7'
+myst-parser==2.0.0
+packaging==23.1; python_version >= '3.7'
+pkginfo==1.9.6; python_version >= '3.6'
+platformdirs==3.8.1; python_version >= '3.7'
+pluggy==1.2.0; python_version >= '3.7'
+pygments==2.15.1; python_version >= '3.7'
+pylint==2.17.4
+pyproject-api==1.5.3; python_version >= '3.7'
+pyproject-hooks==1.0.0; python_version >= '3.7'
+pytest-mock==3.11.1
+pytest==7.4.0
+pyyaml==6.0; python_version >= '3.6'
+readme-renderer==40.0; python_version >= '3.8'
+requests-toolbelt==1.0.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+requests==2.31.0
+rfc3986==2.0.0; python_version >= '3.7'
+rich==13.4.2; python_version >= '3.7'
+six==1.16.0; python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'
+snowballstemmer==2.2.0
+sphinx-rtd-theme==1.2.2
+sphinx==6.2.1
+sphinxcontrib-applehelp==1.0.4; python_version >= '3.8'
+sphinxcontrib-devhelp==1.0.2; python_version >= '3.5'
+sphinxcontrib-htmlhelp==2.0.1; python_version >= '3.8'
+sphinxcontrib-jquery==4.1; python_version >= '2.7'
+sphinxcontrib-jsmath==1.0.1; python_version >= '3.5'
+sphinxcontrib-qthelp==1.0.3; python_version >= '3.5'
+sphinxcontrib-serializinghtml==1.1.5; python_version >= '3.5'
+tomli==2.0.1; python_version < '3.11'
+tomlkit==0.11.8; python_version >= '3.7'
+tox-gh-actions==3.1.3
+tox==4.6.4
+twine==4.0.2
+typing-extensions==4.7.1; python_version < '3.11'
+urllib3==2.0.3; python_full_version >= '3.7.0'
+virtualenv==20.23.1; python_version >= '3.7'
+webencodings==0.5.1
+wrapt==1.15.0; python_version < '3.11'
+zipp==3.16.1; python_version >= '3.8'

docs/source/conf.py

@@ -0,0 +1,33 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Zephyr Python API'
+copyright = '2023, Petr Sharapenko'
+author = 'Petr Sharapenko'
+release = '0.0.4'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.autodoc', 'myst_parser']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/source/examples.md

@@ -0,0 +1,56 @@
+# Examples
+
+## Authentication
+
+Zephyr Cloud auth requires generating an API access token ([see the how-to](https://support.smartbear.com/zephyr-scale-cloud/docs/rest-api/generating-api-access-tokens.html)).
+```python
+from zephyr import ZephyrScale
+
+zscale = ZephyrScale(token="<your_token>")
+```
+
+Zephyr Server/Data Center (TM4J) auth:
+
+```python
+from zephyr import ZephyrScale
+
+# Auth can be made with Jira token
+auth = {"token": "<your_jira_token>"}
+
+# or with login and password (suggest using get_pass)
+auth = {"username": "<your_login>", "password": "<your_password>"}
+
+# or even session cookie dict
+auth = {"cookies": "<session_cookie_dict>"}
+
+zscale = ZephyrScale.server_api(base_url="<your_base_url>", **auth)
+```
+
+## Usage
+
+Then it is possible to interact with the low-level api wrappers:
+```python
+zapi = zscale.api
+
+# Get all test cases
+all_test_cases = zapi.test_cases.get_test_cases()
+
+# Get a single test case by its id
+test_case = zapi.test_cases.get_test_case("<test_case_id>")
+
+# Create a test case
+creation_result = zapi.test_cases.create_test_case("<project_key>", "test_case_name")
+```
+
+Each Zephyr Scale API wrapper group could be accessed as a property:
+```python
+zapi = zscale.api
+
+# Test Cases
+test_case = zapi.test_cases
+
+# Test Cycles
+test_cycles = zapi.test_cycles
+```
+
+Be aware that depending on your API type (Cloud or Server/Datacenter) the amount of wrapper groups and their naming is different.

docs/source/index.rst

@@ -0,0 +1,36 @@
+.. Zephyr Python API documentation master file, created by
+   sphinx-quickstart on Sat Jun 17 21:27:13 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Zephyr Python API's documentation!
+=============================================
+
+The package is a set of python wrappers for Zephyr Scale (TM4J) REST API (both Cloud and Server/DataCenter).
+Interact with Zephyr Scale without GUI, access it with python code and create automation scripts for your daily routines.
+
+The idea of the package is to have two parts in it: a set of low-level wrappers and  Zephyr objects (like a test case or  a test cycle).
+The low-level wrappers are simply performing requests to the API endpoints of Zephyr with no logic added. The Zephyr objects
+is a set of classes where the Zephyr interaction logic is placed. The logic is implemented using the low-level API wrappers.
+Currently the Zephyr objects are not implemented.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   installation
+   examples
+   troubleshooting
+   zephyr
+
+Limitations
+***********
+
+The wrappers only implement public API methods from the official SmartBear Zephyr Scale Cloud and Server/DataCenter APIs.
+
+Useful links
+************
+
+`Zephyr Scale Cloud API docs <https://support.smartbear.com/zephyr-scale-cloud/api-docs/>`_
+
+`Zephyr Scale Server/Data Center API docs <https://support.smartbear.com/zephyr-scale-server/api-docs/v1/>`_

docs/source/installation.rst

@@ -0,0 +1,33 @@
+Installation
+============
+
+From PyPI
+***********
+
+Simply use pip to install `the package from PYPI <https://pypi.org/project/zephyr-python-api/>`_:
+
+.. code-block:: console
+
+   pip install zephyr-python-api
+
+From source
+***********
+
+* Git clone repository
+
+.. code-block:: console
+
+   git clone https://github.com/nassauwinter/zephyr-python-api.git
+
+
+* Install dependencies:
+
+.. code:: console
+
+   pip install -r requirements.txt
+
+* or better with `pipenv <https://pypi.org/project/pipenv/>`_:
+
+.. code:: console
+
+   pipenv install

TROUBLESHOOTING.md → docs/source/troubleshooting.md

@@ -1,5 +1,9 @@
+# Troubleshooting
+
+This section is for some troubleshooting advices and guides.
+
 ## Reporting to Zephyr
 
-- The Cucumber format is different from Behave reporter format.
+The Cucumber tool format is different from python Behave reporter format.
 In case you want to report test executions from output Behave file, 
 please use some custom formatter for Behave output, i.e. https://pypi.org/project/behave-cucumber-formatter/.

requirements.txt

@@ -0,0 +1,13 @@
+#
+# These requirements were autogenerated by pipenv
+# To regenerate from the project's Pipfile, run:
+#
+#    pipenv lock --requirements
+#
+
+-i https://pypi.org/simple
+certifi==2023.5.7; python_version >= '3.6'
+charset-normalizer==3.1.0; python_full_version >= '3.7.0'
+idna==3.4; python_version >= '3.5'
+requests==2.31.0
+urllib3==2.0.3; python_full_version >= '3.7.0'