Skip to content

Commit 0038d36

Browse files
committed
Added readthedocs documentation.
1 parent 4e61948 commit 0038d36

File tree

10 files changed

+628
-0
lines changed

10 files changed

+628
-0
lines changed

.readthedocs.yaml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# .readthedocs.yaml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Set the OS, Python version and other tools you might need
9+
build:
10+
os: ubuntu-22.04
11+
tools:
12+
python: "3.11"
13+
# You can also specify other tool versions:
14+
# nodejs: "19"
15+
# rust: "1.64"
16+
# golang: "1.19"
17+
18+
# Build documentation in the "docs/" directory with Sphinx
19+
sphinx:
20+
configuration: docs/source/conf.py
21+
22+
# Optionally build your docs in additional formats such as PDF and ePub
23+
# formats:
24+
# - pdf
25+
# - epub
26+
27+
# Optional but recommended, declare the Python requirements required
28+
# to build your documentation
29+
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
30+
python:
31+
install:
32+
- requirements: docs/requirements.txt

docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

docs/requirements.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Defining the exact version will make sure things don't break
2+
# Sphinx==6.2.1
3+
sphinx-book-theme==1.0.1
4+
# sphinx-pdj-theme==0.4.0
5+
myst-parser==2.0.0
6+
markdown-it-py==3.0.0
7+
sphinx-copybutton==0.5.2

docs/source/code.md

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# IP2Location PHP API
2+
3+
## Database Class
4+
5+
```{py:class} Database($file, $mode)
6+
Initiate the IP2Location class and load the IP2Location BIN database.
7+
8+
:param str $file: (Required) The file path links to IP2Location BIN databases.
9+
:param str $mode: (Optional) The file mode used to open the IP2Location BIN database. Options available are FILE_IO, SHARED_MEMORY and MEMORY_CACHE. Default is FILE_IO.
10+
```
11+
12+
```{py:function} lookup($ip)
13+
Retrieve geolocation information for an IP address.
14+
15+
:param str $ip: (Required) The IP address (IPv4 or IPv6).
16+
:return: Returns the geolocation information in dict. Refer below table for the fields avaliable in the dict
17+
:rtype: array
18+
19+
**RETURN FIELDS**
20+
21+
| Field Name | Description |
22+
| ---------------- | ------------------------------------------------------------ |
23+
| countryCode | Two-character country code based on ISO 3166. |
24+
| countryName | Country name based on ISO 3166. |
25+
| regionName | Region or state name. |
26+
| cityName | City name. |
27+
| isp | Internet Service Provider or company\'s name. |
28+
| latitude | City latitude. Defaults to capital city latitude if city is unknown. |
29+
| longitude | City longitude. Defaults to capital city longitude if city is unknown. |
30+
| domainName | Internet domain name associated with IP address range. |
31+
| zipCode | ZIP code or Postal code. [172 countries supported](https://www.ip2location.com/zip-code-coverage). |
32+
| timeZone | UTC time zone (with DST supported). |
33+
| netSpeed | Internet connection type. |
34+
| iddCode | The IDD prefix to call the city from another country. |
35+
| areaCode | A varying length number assigned to geographic areas for calls between cities. [223 countries supported](https://www.ip2location.com/area-code-coverage). |
36+
| weatherStationCode | The special code to identify the nearest weather observation station. |
37+
| weatherStationName | The name of the nearest weather observation station. |
38+
| 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. |
39+
| mnc | Mobile Network Code (MNC) is used in combination with a Mobile Country Code(MCC) to uniquely identify a mobile phone operator or carrier. |
40+
| mobileCarrierName | 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. |
41+
| elevation | Average height of city above sea level in meters (m). |
42+
| usageType | Usage type classification of ISP or company. |
43+
| addressType | IP address types as defined in Internet Protocol version 4 (IPv4) and Internet Protocol version 6 (IPv6). |
44+
| category | The domain category based on [IAB Tech Lab Content Taxonomy](https://www.ip2location.com/free/iab-categories). |
45+
| district | District or county name. |
46+
| asn | Autonomous system number (ASN). BIN databases. |
47+
| as | Autonomous system (AS) name. |
48+
```
49+
50+
## IpTools Class
51+
52+
```{py:class} IpTools()
53+
Initiate IpTools class.
54+
```
55+
56+
```{py:function} isIpv4($ip)
57+
Verify if a string is a valid IPv4 address.
58+
59+
:param str $ip: (Required) IP address.
60+
:return: Return True if the IP address is a valid IPv4 address or False if it isn't a valid IPv4 address.
61+
:rtype: boolean
62+
```
63+
64+
```{py:function} isIpv6($ip)
65+
Verify if a string is a valid IPv6 address
66+
67+
:param str $ip: (Required) IP address.
68+
:return: Return True if the IP address is a valid IPv6 address or False if it isn't a valid IPv6 address.
69+
:rtype: boolean
70+
```
71+
72+
```{py:function} ipv4ToDecimal($ip)
73+
Translate IPv4 address from dotted-decimal address to decimal format.
74+
75+
:param str $ip: (Required) IPv4 address.
76+
:return: Return the decimal format of the IPv4 address.
77+
:rtype: int
78+
```
79+
80+
```{py:function} decimalToIpv4($number)
81+
Translate IPv4 address from decimal number to dotted-decimal address.
82+
83+
:param str $number: (Required) Decimal format of the IPv4 address.
84+
:return: Returns the dotted-decimal format of the IPv4 address.
85+
:rtype: string
86+
```
87+
88+
```{py:function} ipv6ToDecimal($ip)
89+
Translate IPv6 address from hexadecimal address to decimal format.
90+
91+
:param str $ip: (Required) IPv6 address.
92+
:return: Return the decimal format of the IPv6 address.
93+
:rtype: int
94+
```
95+
96+
```{py:function} decimalToIpv6($number)
97+
Translate IPv6 address from decimal number into hexadecimal address.
98+
99+
:param str $number: (Required) Decimal format of the IPv6 address.
100+
:return: Returns the hexadecimal format of the IPv6 address.
101+
:rtype: string
102+
```
103+
104+
```{py:function} ipv4ToCidr($ipFrom, $ipTo)
105+
Convert IPv4 range into a list of IPv4 CIDR notation.
106+
107+
:param str $ipFrom: (Required) The starting IPv4 address in the range.
108+
:param str $ipTo: (Required) The ending IPv4 address in the range.
109+
:return: Returns the list of IPv4 CIDR notation.
110+
:rtype: list
111+
```
112+
113+
```{py:function} cidrToIpv4($cidr)
114+
Convert IPv4 CIDR notation into a list of IPv4 addresses.
115+
116+
:param str $cidr: (Required) IPv4 CIDR notation.
117+
:return: Returns an array of IPv4 addresses.
118+
:rtype: dict
119+
```
120+
121+
```{py:function} ipv6ToCidr($ipFrom, $ipTo)
122+
Convert IPv6 range into a list of IPv6 CIDR notation.
123+
124+
:param str $ipFrom: (Required) The starting IPv6 address in the range.
125+
:param str $ipTo: (Required) The ending IPv6 address in the range.
126+
:return: Returns the list of IPv6 CIDR notation.
127+
:rtype: list
128+
```
129+
130+
```{py:function} cidrToIpv6($cidr)
131+
Convert IPv6 CIDR notation into a list of IPv6 addresses.
132+
133+
:param str $cidr: (Required) IPv6 CIDR notation.
134+
:return: Returns an array of IPv6 addresses.
135+
:rtype: dict
136+
```
137+
138+
139+
```{py:function} compressIpv6($ip)
140+
Compress a IPv6 to shorten the length.
141+
142+
:param str $ip: (Required) IPv6 address.
143+
:return: Returns the compressed version of IPv6 address.
144+
:rtype: str
145+
```
146+
147+
```{py:function} expandIpv6($ip)
148+
Expand a shorten IPv6 to full length.
149+
150+
:param str $ip: (Required) IPv6 address.
151+
:return: Returns the extended version of IPv6 address.
152+
:rtype: str
153+
```
154+
155+
```{py:function} getVisitorIp($ipData)
156+
Return the real IP address of the visitor. If an array of $ipData is supplied, it will return the list of IP address data found.
157+
158+
:param array $ipData: (Optional) List of IP addresses.
159+
:return: Returns the extended version of IPv6 address.
160+
:rtype: str
161+
```
162+
163+
## Country Class
164+
165+
```{py:class} Country($csv)
166+
Initiate Country class and load the IP2Location Country Information CSV file. This database is free for download at <https://www.ip2location.com/free/country-information>.
167+
168+
:param str $csv: (Required) The file path links to IP2Location Country Information CSV file.
169+
```
170+
171+
```{py:function} getCountryInfo($countryCode)
172+
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.
173+
174+
:param str $countryCode: (Required) The ISO 3166 country code of a country.
175+
:return: Returns the country information in dict. Refer below table for the fields avaliable in the dict.
176+
:rtype: dict
177+
178+
**RETURN FIELDS**
179+
180+
| Field Name | Description |
181+
| ---------------- | ------------------------------------------------------------ |
182+
| country_code | Two-character country code based on ISO 3166. |
183+
| country_alpha3_code | Three-character country code based on ISO 3166. |
184+
| country_numeric_code | Three-character country code based on ISO 3166. |
185+
| capital | Capital of the country. |
186+
| country_demonym | Demonym of the country. |
187+
| total_area | Total area in km{sup}`2`. |
188+
| population | Population of year 2014. |
189+
| idd_code | The IDD prefix to call the city from another country. |
190+
| currency_code | Currency code based on ISO 4217. |
191+
| currency_name | Currency name. |
192+
| currency_symbol | Currency symbol. |
193+
| lang_code | Language code based on ISO 639. |
194+
| lang_name | Language name. |
195+
| cctld | Country-Code Top-Level Domain. |
196+
```
197+
198+
## Region Class
199+
200+
```{py:class} Region($csv)
201+
Initiate Region 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>
202+
203+
:param str $csv: (Required) The file path links to IP2Location ISO 3166-2 Subdivision Code CSV file.
204+
```
205+
206+
```{py:function} getRegionCode($countryCode, $regionName)
207+
Provide a ISO 3166 country code and the region name to get ISO 3166-2 subdivision code for the region.
208+
209+
:param str $countryCode: (Required) Two-character country code based on ISO 3166.
210+
:param str $regionName: (Required) Region or state name.
211+
:return: Returns the ISO 3166-2 subdivision code of the region.
212+
:rtype: str
213+
```

docs/source/conf.py

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
# Read https://www.sphinx-doc.org/en/master/usage/configuration.html for more options available
3+
4+
# import sphinx_pdj_theme
5+
6+
# -- Project information
7+
8+
project = 'IP2Location'
9+
copyright = '2023, IP2Location'
10+
author = 'IP2Location'
11+
12+
release = '9.7.0'
13+
version = '9.7.0'
14+
15+
# -- General configuration
16+
17+
extensions = [
18+
'sphinx.ext.duration',
19+
'sphinx.ext.doctest',
20+
# 'sphinx.ext.autodoc',
21+
# 'sphinx.ext.autosummary',
22+
# 'sphinx.ext.intersphinx',
23+
'myst_parser',
24+
'sphinx_copybutton',
25+
# "sphinxext.opengraph",
26+
]
27+
28+
# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
29+
30+
myst_enable_extensions = [
31+
# "amsmath",
32+
# "attrs_inline",
33+
"colon_fence",
34+
"deflist",
35+
# "dollarmath",
36+
"fieldlist",
37+
# "html_admonition",
38+
# "html_image",
39+
# "linkify",
40+
# "replacements",
41+
# "smartquotes",
42+
# "strikethrough",
43+
# "substitution",
44+
# "tasklist",
45+
]
46+
47+
# https://myst-parser.readthedocs.io/en/latest/configuration.html#setting-html-metadata
48+
# language = "en"
49+
myst_html_meta = {
50+
"description": "IP2Location PHP library enables user to query the geolocation information for an IP address.",
51+
"keywords": "IP2Location, Geolocation, IP location, PHP",
52+
"google-site-verification": "DeW6mXDyMnMt4i61ZJBNuoADPimo5266DKob7Z7d6i4",
53+
}
54+
55+
# OpenGraph metadata
56+
# ogp_site_url = "https://ip2location-python.readthedocs.io/en/latest"
57+
58+
# -- Options for HTML output
59+
60+
html_theme = 'sphinx_book_theme'
61+
62+
# PDJ theme options, see the list of available options here: https://github.com/jucacrispim/sphinx_pdj_theme/blob/master/sphinx_pdj_theme/theme.conf
63+
html_theme_options = {
64+
"use_edit_page_button": False,
65+
"use_source_button": False,
66+
"use_issues_button": False,
67+
"use_download_button": False,
68+
"use_sidenotes": False,
69+
}
70+
71+
# The name of an image file (relative to this directory) to place at the top
72+
# of the sidebar.
73+
html_logo = 'images/ipl-logo-square-1200.png'
74+
75+
# Favicon
76+
html_favicon = 'images/favicon.ico'
77+
78+
html_title = "IP2Location PHP"
79+
80+
# html_extra_path = ["googlead5f0f82eb100b8b.html"]
81+
82+
# html_baseurl = "https://ip2location-php.readthedocs.io/en/latest/"

docs/source/images/favicon.ico

14.7 KB
Binary file not shown.
19.8 KB
Loading

0 commit comments

Comments
 (0)