Added readthedocs documentation.

ip2location · Aug 11, 2023 · 8de919c · 8de919c
1 parent 5855534
commit 8de919c
Show file tree

Hide file tree

Showing 10 changed files with 496 additions and 0 deletions.
diff --git a/.readthedocs.yaml b/.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
diff --git a/docs/Makefile b/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)
diff --git a/docs/make.bat b/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
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,5 @@
+# Defining the exact version will make sure things don't break
+sphinx-pdj-theme==0.4.0
+myst-parser==2.0.0
+markdown-it-py==3.0.0
+sphinx-copybutton==0.5.2
diff --git a/docs/source/code.md b/docs/source/code.md
@@ -0,0 +1,208 @@
+# IP2Location Ruby API
+
+## IP2Location Class
+
+```{py:class} IP2Location()
+Construct the IP2Location Class.
+```
+
+```{py:function} open(binPath)
+Load the IP2Location BIN database for lookup.
+
+:param str binPath: (Required) The file path links to IP2Location BIN databases.
+```
+
+```{py:function} getAll(ipAddress)
+Retrieve geolocation information for an IP address.
+
+:param str ipAddress: (Required) The IP address (IPv4 or IPv6).
+:return: Returns the geolocation information in array. Refer below table for the fields avaliable in the array
+:rtype: array
+
+**RETURN FIELDS**
+
+| Field Name       | Description                                                  |
+| ---------------- | ------------------------------------------------------------ |
+| countryShort    |     Two-character country code based on ISO 3166. |
+| countryLong     |     Country name based on ISO 3166. |
+| region           |     Region or state name. |
+| city             |     City name. |
+| isp              |     Internet Service Provider or company\'s name. |
+| latitude         |     City latitude. Defaults to capital city latitude if city is unknown. |
+| longitude        |     City longitude. Defaults to capital city longitude if city is unknown. |
+| domain           |     Internet domain name associated with IP address range. |
+| zipCode          |     ZIP code or Postal code. [172 countries supported](https://www.ip2location.com/zip-code-coverage). |
+| timeZone         |     UTC time zone (with DST supported). |
+| netSpeed         |     Internet connection type. |
+| iddCode         |     The IDD prefix to call the city from another country. |
+| areaCode        |     A varying length number assigned to geographic areas for calls between cities. [223 countries supported](https://www.ip2location.com/area-code-coverage). |
+| weatherStationCode     |     The special code to identify the nearest weather observation station. |
+| weatherStationName     |     The name of the nearest weather observation station. |
+| mcc              |     Mobile Country Codes (MCC) as defined in ITU E.212 for use in identifying mobile stations in wireless telephone networks, particularly GSM and UMTS networks. |
+| mnc              |     Mobile Network Code (MNC) is used in combination with a Mobile Country Code(MCC) to uniquely identify a mobile phone operator or carrier. |
+| mobileBrand     |     Commercial brand associated with the mobile carrier. You may click [mobile carrier coverage](https://www.ip2location.com/mobile-carrier-coverage) to view the coverage report. |
+| elevation        |     Average height of city above sea level in meters (m). |
+| usageType       |     Usage type classification of ISP or company. |
+| addressType     |     IP address types as defined in Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6). |
+| category         |     The domain category based on [IAB Tech Lab Content Taxonomy](https://www.ip2location.com/free/iab-categories). |
+| district         |     District or county name. |
+| asn              |     Autonomous system number (ASN). BIN databases. |
+| as          |     Autonomous system (AS) name. |
+```
+
+## IPTools Class
+
+```{py:class} IPTools ()
+Initiate IPTools class.
+```
+
+```{py:function} isIPV4(ipAddress)
+Verify if a string is a valid IPv4 address.
+
+:param str ipAddress: (Required) IP address.
+:return: Return True if the IP address is a valid IPv4 address or False if it isn't a valid IPv4 address.
+:rtype: boolean
+```
+
+```{py:function} isIPV6(ipAddress)
+Verify if a string is a valid IPv6 address
+
+:param str ipAddress: (Required) IP address.
+:return: Return True if the IP address is a valid IPv6 address or False if it isn't a valid IPv6 address.
+:rtype: boolean
+```
+
+```{py:function} ipV4ToDecimal(ipAddress)
+Translate IPv4 address from dotted-decimal address to decimal format.
+
+:param str ipAddress: (Required) IPv4 address.
+:return: Return the decimal format of the IPv4 address.
+:rtype: int
+```
+
+```{py:function} decimalToIPV4(ipNumber)
+Translate IPv4 address from decimal number to dotted-decimal address.
+
+:param str ip_number: (Required) Decimal format of the IPv4 address.
+:return: Returns the dotted-decimal format of the IPv4 address.
+:rtype: string
+```
+
+```{py:function} ipV6ToDecimal(ipAddress)
+Translate IPv6 address from hexadecimal address to decimal format.
+
+:param str ipAddress: (Required) IPv6 address.
+:return: Return the decimal format of the IPv6 address.
+:rtype: int
+```
+
+```{py:function} decimalToIPV6(ipNumber)
+Translate IPv6 address from decimal number into hexadecimal address.
+
+:param str ip_number: (Required) Decimal format of the IPv6 address.
+:return: Returns the hexadecimal format of the IPv6 address.
+:rtype: string
+```
+
+```{py:function} ipV4ToCIDR(ip_from, ip_to)
+Convert IPv4 range into a list of IPv4 CIDR notation.
+
+:param str ip_from: (Required) The starting IPv4 address in the range.
+:param str ip_to: (Required) The ending IPv4 address in the range.
+:return: Returns the list of IPv4 CIDR notation.
+:rtype: array
+```
+
+```{py:function} cidrToIPV4(cidr)
+Convert IPv4 CIDR notation into a list of IPv4 addresses.
+
+:param str cidr: (Required) IPv4 CIDR notation.
+:return: Returns an list of IPv4 addresses.
+:rtype: array
+```
+
+```{py:function} ipV6ToCIDR(ip_from, ip_to)
+Convert IPv6 range into a list of IPv6 CIDR notation.
+
+:param str ip_from: (Required) The starting IPv6 address in the range.
+:param str ip_to: (Required) The ending IPv6 address in the range.
+:return: Returns the list of IPv6 CIDR notation.
+:rtype: array
+```
+
+```{py:function} cidrToIPV6(cidr)
+Convert IPv6 CIDR notation into a list of IPv6 addresses.
+
+:param str cidr: (Required) IPv6 CIDR notation.
+:return: Returns an list of IPv6 addresses.
+:rtype: array
+```
+
+
+```{py:function} compressIPV6(ipAddress)
+Compress a IPv6 to shorten the length.
+
+:param str ipAddress: (Required) IPv6 address.
+:return: Returns the compressed version of IPv6 address.
+:rtype: str
+```
+
+```{py:function} expandIPV6(ipAddress)
+Expand a shorten IPv6 to full length.
+
+:param str ipAddress: (Required) IPv6 address.
+:return: Returns the extended version of IPv6 address.
+:rtype: str
+```
+
+## Country Class
+
+```{py:class} Country(csvFilePath)
+Initiate Ip2locationCountry class and load the IP2Location Country Information CSV file. This database is free for download at <https://www.ip2location.com/free/country-information>.
+
+:param str csvFilePath: (Required) The file path links to IP2Location Country Information CSV file.
+```
+
+```{py:function} getCountryInfo(countryCode)
+Provide a ISO 3166 country code to get the country information in array. Will return a full list of countries information if country code not provided. 
+
+:param str countryCode: (Required) The ISO 3166 country code of a country.
+:return: Returns the country information in array. Refer below table for the fields avaliable in the array.
+:rtype: array
+
+**RETURN FIELDS**
+
+| Field Name       | Description                                                  |
+| ---------------- | ------------------------------------------------------------ |
+| countryCode     | Two-character country code based on ISO 3166.                |
+| countryAlpha3Code | Three-character country code based on ISO 3166.           |
+| countryNumericCode | Three-character country code based on ISO 3166.          |
+| capital          | Capital of the country.                                      |
+| countryDemonym  | Demonym of the country.                                      |
+| totalArea       | Total area in km{sup}`2`.                                    |
+| population       | Population of year 2014.                                     |
+| idd_code         | The IDD prefix to call the city from another country.        |
+| currencyCode    | Currency code based on ISO 4217.                             |
+| currencyName    | Currency name.                                               |
+| currencySymbol  | Currency symbol.                                             |
+| langCode        | Language code based on ISO 639.                              |
+| langName        | Language name.                                               |
+| cctld            | Country-Code Top-Level Domain.                               |
+```
+
+## Region Class
+
+```{py:class} Region(csvFilePath)
+Initiate Ip2locationRegion class and load the IP2Location ISO 3166-2 Subdivision Code CSV file. This database is free for download at <https://www.ip2location.com/free/iso3166-2>
+
+:param str csvFilePath: (Required) The file path links to IP2Location ISO 3166-2 Subdivision Code CSV file.
+```
+
+```{py:function} getRegionCode(countryCode, regionName)
+Provide a ISO 3166 country code and the region name to get ISO 3166-2 subdivision code for the region.
+
+:param str countryCode: (Required) Two-character country code based on ISO 3166.
+:param str regionName: (Required) Region or state name.
+:return: Returns the ISO 3166-2 subdivision code of the region.
+:rtype: str
+```
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,52 @@
+# 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 = 'IP2Location Node.js'
+copyright = '2023, IP2Location'
+author = 'IP2Location'
+
+release = '1.0.0'
+version = '1.0.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",
+]
+
+# templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_pdj_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 = {
+    # Hide the name of the project above the search bar
+    'home_link': 'hide'
+}
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'images/ipl-logo-square-1200.png'
+
+# Favicon
+html_favicon = 'images/favicon.ico'
+
+html_title = "IP2Location Python"
diff --git a/docs/source/images/favicon.ico b/docs/source/images/favicon.ico
diff --git a/docs/source/images/ipl-logo-square-1200.png b/docs/source/images/ipl-logo-square-1200.png
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -0,0 +1,30 @@
+[![npm](https://img.shields.io/npm/v/ip2location-nodejs.svg)](http://npm.im/ip2location-nodejs)
+[![npm](https://img.shields.io/npm/dm/ip2location-nodejs.svg)](http://npm.im/ip2location-nodejs)
+# IP2Location Node.js Library
+
+This Node.js module provides a fast lookup of country, region, city, latitude, longitude, ZIP code, time zone, ISP, domain name, connection type, IDD code, area code, weather station code, station name, mcc, mnc, mobile brand, elevation, usage type, address type, IAB category, district, autonomous system number (ASN) and autonomous system (AS) from IP address by using IP2Location database. This module uses a file based database available at IP2Location.com. This database simply contains IP blocks as keys, and other information such as country, region, city, latitude, longitude, ZIP code, time zone, ISP, domain name, connection type, IDD code, area code, weather station code, station name, mcc, mnc, mobile brand, elevation, usage type, address type, IAB category, district, autonomous system number (ASN) and autonomous system (AS) as values. It supports both IP address in IPv4 and IPv6.
+
+This module can be used in many types of projects such as:
+
+ - select the geographically closest mirror
+ - analyze your web server logs to determine the countries of your visitors
+ - credit card fraud detection
+ - software export controls
+ - display native language and currency 
+ - prevent password sharing and abuse of service 
+ - geotargeting in advertisement
+
+The database will be updated on a monthly basis for greater accuracy.
+
+The complete database is available at https://www.ip2location.com under Premium subscription package.
+The free LITE database is available at https://lite.ip2location.com.
+
+
+## Table of contents
+ ```{eval-rst}
+ .. toctree::
+
+   self
+   quickstart
+   code
+ ```