Doc/project documentation (#38)

* Add project documentation

* Add readthedocs configuration

* Fix Python code blocks highlighting

Author: ebram96

.gitignore

@@ -15,3 +15,6 @@ __pycache__/
 
 # Tox
 .tox
+
+# Docs build
+docs/build/

.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 fail_fast: true
+exclude: ^(docs|README\.md)/
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+   install:
+   - requirements: docs/requirements.txt

README.md

@@ -1 +1,256 @@
-# TODO
+# Abstract API Python SDK
+
+This is a simple and intuitive Python SDK for using [AbstractAPI's](https://www.abstractapi.com/) services.
+
+Current supported services:
+===========================
+All AbstractAPI services are supported by this SDK (16th. January 2023).
+- Email Validation
+- Phone Validation
+- VAT Validation/Calculation/Categories
+- IBAN Validation
+- IP Geolocation
+- Holidays Lookup
+- Exchange Rates Live/Convert/Historical
+- Company Enrichment
+- Timezone Current/Conversion
+- Avatars Generation
+- Website Screenshot
+- Website Scrape
+- Image Processing
+
+Installation:
+=============
+Install using `pip`:
+
+    pip install abstract-api
+
+Getting Started:
+================
+To use any service, you must have your API key for that service.\
+To do that, you have two options:
+1. Export your API key as an environment variable:\
+   To export an API key for a service, you should follow this scheme:
+   ```
+   ABSTRACTAPI_{SERVICE_NAME}_API_KEY
+   ```
+   Note: `SERVICE_NAME` is all uppercase and underscore separated.\
+   For example, to export your Email Validation service API key, use the following environment variable name:
+   ```
+   ABSTRACTAPI_EMAIL_VALIDATION_API_KEY
+   ```
+   Example in terminal:
+   ```shell
+   export ABSTRACTAPI_AVATARS_API_KEY=612345e4a63044b47a1234567a53cc81
+   ```
+   In initialization, you don't have to pass an API key:
+   ```python
+   from abstract_api import EmailValidation
+
+   service = EmailValidation()
+   ```
+2. Pass your API key during service class instantiation:\
+   Example:
+   ```python
+   from abstract_api import EmailValidation
+
+   service = EmailValidation(api_key="612345e4a63044b47a1234567a53cc81")
+   ```
+
+**Note**:
+If both options were used simultaneously, the API key that was passed to constructor is used.
+
+Examples:
+=========
+**Notes**:
+- Each service response is represented as a response class to provide an intuitive\
+Pythonic way for handling responses.
+- All public interfaces of all services classes are modeled after AbstractAPI endpoints interfaces and responses.\
+  Example: Email Validation service endpoint expects the following parameters:
+  - `api_key`
+  - `email`
+  - `auto_correct`\
+  The `EmailValidation` class's `check()` method expects the same parameters `email` and `auto_correct`.\
+  (No need to pass `api_key`. It is already passed during service instantiation.)
+
+**Recommended**:\
+- Check service class and service class response documentations.
+- Response fields used in examples are not only the ones. Check documentation to see\
+  all the capabilities.
+
+- Email Validation
+  ```python
+  from abstract_api import EmailValidation
+  service = EmailValidation(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.check("example@example.com")
+  if response.is_valid_format:
+     print("Email is valid!")
+  if response.is_disposable_email:
+     print("Email is disposable, not this time :( ")
+  ```
+  `EmailValidation` documentation can be found [here](TODO)\
+  `EmailValidationResponse` documentation can be found [here](TODO)
+
+- Phone Validation
+  ```python
+  from abstract_api import PhoneValidation
+  service = PhoneValidation(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.check("20123456789")
+  if response.valid:
+     print("Phone number is valid!")
+  ```
+  `PhoneValidation` documentation can be found [here](TODO)\
+  `PhoneValidationResponse` documentation can be found [here](TODO)
+
+- VAT Validation/Calculation/Inquiry
+  ```python
+  from abstract_api import VAT
+  service = VAT(api_key="612345e4a63044b47a1234567a53cc81")
+  validation_response = service.check("SE556656688001")
+  calculation_response = service.calculate(amount=100, country_code="EG")
+  categories_response = service.categories("EG")
+  ```
+  `VAT` documentation can be found [here](TODO)\
+  `VATValidationResponse` documentation can be found [here](TODO)\
+  `VATCalculationResponse` documentation can be found [here](TODO)\
+  `VATCategoriesResponse` documentation can be found [here](TODO)
+
+- IBAN Validation
+  ```python
+  from abstract_api import IBANValidation
+  service = IBANValidation(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.check("BE71096123456769")
+  if response.is_valid:
+     print("IBAN is valid!")
+  ```
+  `IBANValidation` documentation can be found [here](TODO)\
+  `IBANValidationResponse` documentation can be found [here](TODO)
+
+- IP Geolocation
+  ```python
+  from abstract_api import IPGeolocation
+  service = IPGeolocation(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.check("156.215.70.7", fields=["city"])
+  print("IP is in: ", response.city)
+  ```
+  `IPGeolocation` documentation can be found [here](TODO)\
+  `IPGeolocationResponse` documentation can be found [here](TODO)
+
+- Holidays Lookup
+  ```python
+  from abstract_api import Holidays
+  service = Holidays(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.check("EG")
+  print(response.holidays)
+  ```
+  `Holidays` documentation can be found [here](TODO)\
+  `HolidaysResponse` documentation can be found [here](TODO)
+
+- Exchange Rates Live/Convert/Historical
+  ```python
+  from abstract_api import ExchangeRates
+  service = ExchangeRates(api_key="612345e4a63044b47a1234567a53cc81")
+  live_response = service.live("USD", "EGP")
+  conversion_response = service.convert("USD", "EGP", "2023-01-17", 150)
+  historical_response = service.historical("USD", "2023-01-17", 150)
+  ```
+  `ExchangeRates` documentation can be found [here](TODO)\
+  `LiveExchangeRatesResponse` documentation can be found [here](TODO)\
+  `HistoricalExchangeRatesResponse` documentation can be found [here](TODO)\
+  `ExchangeRatesConversionResponse` documentation can be found [here](TODO)
+
+- Company Enrichment
+  ```python
+  from abstract_api import CompanyEnrichment
+  service = CompanyEnrichment(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.check("EG")
+  print(response.holidays)
+  ```
+  `CompanyEnrichment` documentation can be found [here](TODO)\
+  `CompanyEnrichmentResponse` documentation can be found [here](TODO)
+
+- Timezone Current/Conversion
+  ```python
+  from abstract_api import Timezone
+  service = Timezone(api_key="612345e4a63044b47a1234567a53cc81")
+  current_response = service.current("Cairo, Egypt", "82.111.111.111")
+  conversion_response = service.convert((30.0594627, 31.1758899), "Cairo, Egypt")
+  ```
+  `Timezone` documentation can be found [here](TODO)\
+  `CurrentTimezoneResponse` documentation can be found [here](TODO)\
+  `TimezoneConversionResponse` documentation can be found [here](TODO)
+
+- Avatars Generation
+  ```python
+  from abstract_api import Avatars
+  service = Avatars(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.create("John Doe", 200)
+  file = open("logo.png", "wb+")
+  file.write(response.content)
+  ```
+  `Avatars` documentation can be found [here](TODO)\
+  `AvatarsResponse` documentation can be found [here](TODO)
+
+- Website Screenshot
+  ```python
+  from abstract_api import WebsiteScreenshot
+  service = WebsiteScreenshot(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.capture("https://www.github.com", capture_full_page=False)
+  file = open("github-home-screenshot.png", "wb+")
+  file.write(response.content)
+  ```
+  `WebsiteScreenshot` documentation can be found [here](TODO)\
+  `WebsiteScreenshotResponse` documentation can be found [here](TODO)
+
+- Website Scrape
+  ```python
+  from abstract_api import WebScraping
+  service = WebScraping(api_key="612345e4a63044b47a1234567a53cc81")
+  response = service.scrape("https://www.github.com", proxy_country="EG")
+  file = open("github-home-screenshot.png", "wb+")
+  file.write(response.content)
+  ```
+  `WebScraping` documentation can be found [here](TODO)\
+  `WebScrapingResponse` documentation can be found [here](TODO)
+
+- Image Processing
+  ```python
+  from abstract_api import ImageProcessing
+  from abstract_api.image_processing.strategies import Crop, Exact
+  resize = Exact(height=200, width=200)
+  service = ImageProcessing(api_key="612345e4a63044b47a1234567a53cc81")
+  image = open('example.png', 'rb')
+  response = service.upload(image, lossy=False, resize=resize)
+  print(response.url)
+  response = service.url("https://example.com/image.jpeg", lossy=False, resize=resize)
+  print(response.url)
+  ```
+  `ImageProcessing` documentation can be found [here](TODO)\
+  `ImageProcessingResponse` documentation can be found [here](TODO)
+
+### Handling Errors
+1. If something wrong happened on client side:
+  ```python
+  from abstract_api import ImageProcessing
+  from abstract_api.core.exceptions import ClientRequestError
+  service = ImageProcessing(api_key="612345e4a63044b47a1234567a53cc81")
+  try:
+      service.url("https://example.com/image.jpeg", quality=150)
+  except ClientRequestError as e:
+      print("Some error happended from client's side")
+      print(str(e))
+  'quality must be in range from 1 to 100 (inclusive)'
+  ```
+2. If the service endpoint returns a status code that is not 200 or 204.\
+   (200 and 204 are -currently- the only accepted status codes.)
+  ```python
+  from abstract_api import ImageProcessing
+  from abstract_api.core.exceptions import APIRequestError
+  service = ImageProcessing(api_key="612345e4a63044b47a1234567a53cc81")
+  try:
+      service.url("https://example.com/image.jpeg", quality=150)
+  except APIRequestError as e:
+      if e.status_code == 500:
+          print("AbstractAPI service is currently having a problem")
+      print(str(e))
+  ```

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/README.md

@@ -0,0 +1,12 @@
+# Developing Documentation
+
+
+Installation:
+=============
+After installing the SDK, install docs requirements (docs/requirements.txt) using `pip`:
+
+    pip install -r requirements.txt
+
+Getting Started:
+================
+In `docs` directory, run `make html` to generate HTML documentation.

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,25 @@
+alabaster==0.7.16
+Babel==2.14.0
+beautifulsoup4==4.12.3
+docutils==0.20.1
+furo==2023.9.10
+imagesize==1.4.1
+importlib-metadata==7.0.1
+Jinja2==3.1.3
+markdown-it-py==3.0.0
+MarkupSafe==2.1.3
+mdit-py-plugins==0.4.0
+mdurl==0.1.2
+myst-parser==2.0.0
+Pygments==2.17.2
+snowballstemmer==2.2.0
+soupsieve==2.5
+Sphinx==7.2.6
+sphinx-basic-ng==1.0.0b2
+sphinxcontrib-applehelp==1.0.8
+sphinxcontrib-devhelp==1.0.6
+sphinxcontrib-htmlhelp==2.0.5
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.7
+sphinxcontrib-serializinghtml==1.1.10
+zipp==3.17.0

docs/source/api_reference/abstract_api.avatars.avatars.rst

@@ -0,0 +1,7 @@
+abstract\_api.avatars.avatars module
+====================================
+
+.. automodule:: abstract_api.avatars.avatars
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api_reference/abstract_api.avatars.avatars_response.rst

@@ -0,0 +1,7 @@
+abstract\_api.avatars.avatars\_response module
+==============================================
+
+.. automodule:: abstract_api.avatars.avatars_response
+   :members:
+   :undoc-members:
+   :show-inheritance: