Add Readthedocs documentation.

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# 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.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# 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

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,6 @@
+# Defining the exact version will make sure things don't break
+sphinx-book-theme==1.0.1
+# sphinx-pdj-theme==0.4.0
+myst-parser==2.0.0
+markdown-it-py==3.0.0
+sphinx-copybutton==0.5.2

docs/source/code.md

@@ -0,0 +1,97 @@
+# MailboxValidator Ruby API
+
+## MBV Class
+```{py:function} new()
+Creates a new instance of the MailboxValidator object.
+```
+
+```{py:function} query_single(email)
+Validate whether an email address is a valid email or not.
+
+:param str email: (Required) The email address.
+
+:return: Returns the validation result in JSON object.
+:rtype: Object
+
+**Successful Response Parameters**
+| Field Name | Description |
+|-----------|------------|
+| email_address | The input email address. |
+| base_email_address | The input email address after sanitizing the username of the dots (only Gmail) and [subaddressing](https://en.wikipedia.org/wiki/Email_address#Sub-addressing). |
+| domain | The domain of the email address. |
+| is_free | Whether the email address is from a free email provider like Gmail or Hotmail. Return values: true, false, null  (null means not applicable) |
+| is_syntax | Whether the email address is syntactically correct. Return values: true, false |
+| is_domain | Whether the email address has a valid MX record in its DNS entries. Return values: true, false, null  (null means not applicable) |
+| is_smtp | Whether the mail servers specified in the MX records are responding to connections. Return values: true, false, null  (null means not applicable) |
+| is_verified | Whether the mail server confirms that the email address actually exist. Return values: true, false, null  (null means not applicable) |
+| is_server_down | Whether the mail server is currently down or unresponsive. Return values: true, false, null  (null means not applicable) |
+| is_greylisted | Whether the mail server employs greylisting where an email has to be sent a second time at a later time. Return values: true, false, null  (null means not applicable) |
+| is_disposable | Whether the email address is a temporary one from a disposable email provider. Return values: true, false, null  (null means not applicable) |
+| is_suppressed | Whether the email address is in our blacklist. Return values: true, false, null  (null means not applicable) |
+| is_role | Whether the email address is a role-based email address like [email protected] or [email protected]. Return values: true, false, null  (null means not applicable) |
+| is_high_risk | Whether the email address contains high risk keywords. Return values: true, false, null  (null means not applicable) |
+| is_catchall | Whether the email address is a catch-all address. Return values: true, false, null  (null means not applicable) |
+| is_dmarc_enforced | Whether the email domain is enforcing DMARC. Return values: true, false |
+| is_strict_spf | Whether the email domain is using strict SPF. Return values: true, false |
+| website_exist | Whether the email domain is a reachable website. Return values: true, false |
+| mailboxvalidator_score | Email address reputation score. Score > 0.70 means good; score > 0.40 means fair; score <= 0.40 means poor. |
+| time_taken | The time taken to get the results in seconds. |
+| status | Whether our system think the email address is valid based on all the previous fields. Return values: True, False |
+| credits_available | The number of credits left to perform validations. |
+
+**Error Response Parameters**
+| Field Name | Description |
+|-----------|------------|
+| error.error_code | The error code if there is any error. See error table in the [Error Codes](reference.md) section. |
+| error.error_message | The error message if there is any error. See error table in the [Error Codes](reference.md) section. |
+
+```
+
+```{py:function} disposable_email(email)
+Validate whether an email address is a disposable email or not.
+
+:param str email: (Required) The email address.
+
+:return: Returns the validation result in JSON object.
+:rtype: Object
+
+**Successful Response Parameters**
+| Field Name | Description |
+|-----------|------------|
+| email_address | The input email address. |
+| is_disposable | Whether the email address is a temporary one from a disposable email provider. Return values: True, False |
+| credits_available | The number of credits left to perform validations. |
+
+
+**Error Response Parameters**
+| Field Name | Description |
+|-----------|------------|
+| error.error_code | The error code if there is any error. See error table in the [Error Codes](reference.md) section. |
+| error.error_message | The error message if there is any error. See error table in the [Error Codes](reference.md) section. |
+
+```
+
+```{py:function} free_email(email)
+Validate whether an email address is a free email or not.
+
+:param str email: (Required) The email address.
+
+:return: Returns the validation result in JSON object.
+:rtype: Object
+
+**Successful Response Parameters**
+| Field Name | Description |
+|-----------|------------|
+| email_address | The input email address. |
+| is_free | Whether the email address is from a free email provider like Gmail or Hotmail. Return values: True, False |
+| credits_available | The number of credits left to perform validations. |
+
+
+**Error Response Parameters**
+| Field Name | Description |
+|-----------|------------|
+| error.error_code | The error code if there is any error. See error table in the [Error Codes](reference.md) section. |
+| error.error_message | The error message if there is any error. See error table in the [Error Codes](reference.md) section. |
+
+```
+

docs/source/conf.py

@@ -0,0 +1,64 @@
+# Configuration file for the Sphinx documentation builder.
+# Read https://www.sphinx-doc.org/en/master/usage/configuration.html for more options available
+
+# import sphinx_pdj_theme
+
+# -- Project information
+
+project = 'MailboxValidator Ruby'
+copyright = '2024, MailboxValidator'
+author = 'MailboxValidator'
+
+release = '0.1.0'
+version = '0.1.0'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'myst_parser',
+    'sphinx_copybutton',
+]
+
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "fieldlist",
+]
+
+# https://myst-parser.readthedocs.io/en/latest/configuration.html#setting-html-metadata
+myst_html_meta = {
+    "description": "MailboxValidator Ruby module enable users to block disposal email, detect free email and validate if an email is valid.",
+    "keywords": "MailboxValidator, Email Validation, disposable email, free email, Ruby",
+    "google-site-verification": "DeW6mXDyMnMt4i61ZJBNuoADPimo5266DKob7Z7d6i4",
+}
+
+# templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_book_theme'
+# html_theme_path = [sphinx_pdj_theme.get_html_theme_path()]
+
+# PDJ theme options, see the list of available options here: https://github.com/jucacrispim/sphinx_pdj_theme/blob/master/sphinx_pdj_theme/theme.conf
+html_theme_options = {
+    "use_edit_page_button": False,
+    "use_source_button": False,
+    "use_issues_button": False,
+    "use_download_button": False,
+    "use_sidenotes": False,
+}
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'images/mbv-logo-square-1200.png'
+
+# Favicon
+html_favicon = 'images/favicon.ico'
+
+html_title = "MailboxValidator Ruby"
+
+# html_baseurl = "https://ip2proxy-php.readthedocs.io/en/latest/"

docs/source/index.md

@@ -0,0 +1,25 @@
+[![Latest Stable Version](https://img.shields.io/gem/v/mailboxvalidator_ruby.svg)](https://rubygems.org/gems/mailboxvalidator_ruby)
+[![Total Downloads](https://img.shields.io/gem/dt/mailboxvalidator_ruby.svg)](https://rubygems.org/gems/mailboxvalidator_ruby)
+
+MailboxValidator Ruby Module
+============================
+
+This Ruby module enables user to easily validate if an email address is valid, a type of disposable email or free email.
+
+This module can be useful in many types of projects, for example:
+
+ - to validate an user's email during sign up
+ - to clean your mailing list prior to email sending
+ - to perform fraud check
+ - and so on
+
+
+## Table of contents
+ ```{eval-rst}
+ .. toctree::
+
+   self
+   quickstart
+   code
+   reference
+ ```