Skip to content

Commit 08d6547

Browse files
arman-bdarman-bd
committed
docs: Add basic ReadTheDocs documentation with Sphinx
Set up minimal but functional documentation structure for ReadTheDocs: Configuration: - Updated .readthedocs.yaml to use Sphinx instead of Jekyll - Added docs/requirements.txt with Sphinx dependencies - Configured Sphinx with Read the Docs theme Documentation Pages: - index.rst: Main page with overview, features, and quick examples - quickstart.rst: Installation and basic usage guide - api.rst: API reference for Client, Session, and Response classes Features: - All pages include clear notes that comprehensive documentation will be added in the next update - Includes performance benchmarks (3-4x faster than requests) - Documents HTTP/2 support and browser fingerprinting - Basic API reference with common parameters Build System: - Makefile for Linux/Mac - make.bat for Windows - Documentation builds successfully with `make html` - Build artifacts properly ignored in .gitignore Ready for ReadTheDocs deployment
1 parent fbbe7cb commit 08d6547

File tree

10 files changed

+533
-9
lines changed

10 files changed

+533
-9
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ dmypy.json
4747

4848
# Documentation
4949
docs/_build/
50+
docs/build/
5051

5152
# Virtual environments
5253
venv/

‎.readthedocs.yaml‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,19 @@
44
# Required
55
version: 2
66

7-
# Set the OS, Python version, and other tools you might need
7+
# Set the OS, Python version and other tools you might need
88
build:
99
os: ubuntu-24.04
1010
tools:
11-
ruby: "3.3"
11+
python: "3.11"
1212

13-
commands:
14-
# Install dependencies
15-
- gem install bundler
16-
- bundle install
17-
# Build the site and save generated files into Read the Docs directory
18-
- jekyll build --destination $READTHEDOCS_OUTPUT/html
19-
13+
# Build documentation in the docs/ directory with Sphinx
14+
sphinx:
15+
configuration: docs/source/conf.py
16+
17+
# Install Python dependencies required to build your docs
18+
python:
19+
install:
20+
- requirements: docs/requirements.txt
21+
- method: pip
22+
path: .

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# httpmorph Documentation
2+
3+
This directory contains the documentation for httpmorph, built with [Sphinx](https://www.sphinx-doc.org/).
4+
5+
## Building the Documentation Locally
6+
7+
### Prerequisites
8+
9+
Install the documentation dependencies:
10+
11+
```bash
12+
pip install -r requirements.txt
13+
```
14+
15+
### Build HTML Documentation
16+
17+
```bash
18+
cd docs
19+
make html
20+
```
21+
22+
The built documentation will be in `build/html/`. Open `build/html/index.html` in your browser.
23+
24+
### Other Build Targets
25+
26+
```bash
27+
make clean # Remove built documentation
28+
make help # Show all available targets
29+
```
30+
31+
## Documentation Structure
32+
33+
- `source/` - Documentation source files (reStructuredText)
34+
- `index.rst` - Main documentation page
35+
- `quickstart.rst` - Quick start guide
36+
- `api.rst` - API reference
37+
- `conf.py` - Sphinx configuration
38+
39+
## ReadTheDocs
40+
41+
The documentation is automatically built and hosted on ReadTheDocs when changes are pushed to the repository.
42+
43+
Configuration: `.readthedocs.yaml` in the project root
44+
45+
## Contributing to Documentation
46+
47+
Documentation contributions are welcome! Please:
48+
49+
1. Edit the `.rst` files in `source/`
50+
2. Build locally to verify your changes: `make html`
51+
3. Submit a pull request
52+
53+
## Current Status
54+
55+
This is an initial documentation release. Comprehensive documentation including:
56+
57+
- Detailed API reference
58+
- Advanced usage guides
59+
- Examples and tutorials
60+
- Browser fingerprinting details
61+
- Performance tuning guides
62+
- HTTP/2 configuration
63+
64+
...will be added in future updates.

‎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: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx>=7.0
2+
sphinx-rtd-theme>=1.3.0
3+
myst-parser>=2.0.0

‎docs/source/api.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
API Reference
2+
=============
3+
4+
.. note::
5+
This is a minimal API reference. Comprehensive API documentation with detailed
6+
descriptions, examples, and advanced usage will be added in the next update.
7+
8+
Top-Level Functions
9+
-------------------
10+
11+
.. code-block:: python
12+
13+
import httpmorph
14+
15+
# Simple HTTP methods
16+
response = httpmorph.get(url, **kwargs)
17+
response = httpmorph.post(url, **kwargs)
18+
response = httpmorph.put(url, **kwargs)
19+
response = httpmorph.delete(url, **kwargs)
20+
response = httpmorph.head(url, **kwargs)
21+
response = httpmorph.options(url, **kwargs)
22+
response = httpmorph.patch(url, **kwargs)
23+
24+
Client Class
25+
------------
26+
27+
.. code-block:: python
28+
29+
import httpmorph
30+
31+
# Create a client
32+
client = httpmorph.Client(http2=False, timeout=30)
33+
34+
# Make requests
35+
response = client.get(url, **kwargs)
36+
response = client.post(url, **kwargs)
37+
# ... other HTTP methods
38+
39+
**Constructor Parameters:**
40+
41+
* ``http2`` (bool): Enable HTTP/2 support. Default: ``False``
42+
* ``timeout`` (int): Default timeout in seconds. Default: ``30``
43+
44+
Session Class
45+
-------------
46+
47+
.. code-block:: python
48+
49+
import httpmorph
50+
51+
# Create a session
52+
session = httpmorph.Session(browser='chrome', http2=False)
53+
54+
# Use as context manager
55+
with httpmorph.Session(browser='chrome') as session:
56+
response = session.get(url)
57+
58+
**Constructor Parameters:**
59+
60+
* ``browser`` (str): Browser to mimic. Options: ``'chrome'``, ``'firefox'``, ``'safari'``, ``'edge'``, ``'random'``. Default: ``'chrome'``
61+
* ``http2`` (bool): Enable HTTP/2 support. Default: ``False``
62+
63+
**Attributes:**
64+
65+
* ``cookie_jar``: Cookie storage for the session
66+
67+
Response Class
68+
--------------
69+
70+
All requests return a ``Response`` object:
71+
72+
.. code-block:: python
73+
74+
response = httpmorph.get('https://example.com')
75+
76+
**Attributes:**
77+
78+
Basic Response Information
79+
~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
81+
* ``status_code`` (int): HTTP status code
82+
* ``body`` (bytes): Response body
83+
* ``headers`` (dict): Response headers
84+
* ``history`` (list): Redirect history
85+
86+
Timing Information
87+
~~~~~~~~~~~~~~~~~~
88+
89+
* ``total_time_us`` (int): Total request time in microseconds
90+
* ``first_byte_time_us`` (int): Time to first byte in microseconds
91+
* ``connect_time_us`` (int): Connection establishment time in microseconds
92+
* ``tls_time_us`` (int): TLS handshake time in microseconds (HTTPS only)
93+
94+
TLS Information
95+
~~~~~~~~~~~~~~~
96+
97+
* ``tls_version`` (str): TLS version (e.g., ``"TLSv1.3"``)
98+
* ``tls_cipher`` (str): Cipher suite name
99+
* ``ja3_fingerprint`` (str): JA3 TLS fingerprint
100+
101+
HTTP Version Information
102+
~~~~~~~~~~~~~~~~~~~~~~~~
103+
104+
* ``http_version`` (str): HTTP protocol version (e.g., ``"1.1"`` or ``"2.0"``)
105+
106+
Common Request Parameters
107+
-------------------------
108+
109+
Most request methods accept these common parameters:
110+
111+
.. code-block:: python
112+
113+
response = httpmorph.get(
114+
url,
115+
headers=None, # Dict of HTTP headers
116+
params=None, # Dict of URL parameters
117+
json=None, # Dict to send as JSON body
118+
data=None, # String/bytes to send as body
119+
timeout=30, # Request timeout in seconds
120+
http2=None, # Override HTTP/2 setting
121+
follow_redirects=True, # Follow HTTP redirects
122+
)
123+
124+
Full API Documentation
125+
----------------------
126+
127+
Comprehensive API documentation including:
128+
129+
* Detailed method signatures
130+
* Parameter descriptions and types
131+
* Return value specifications
132+
* Exception handling
133+
* Advanced configuration options
134+
* Internal APIs
135+
136+
...will be available in the next update.
137+
138+
For now, please refer to:
139+
140+
* The source code in ``src/httpmorph/``
141+
* Examples in the ``examples/`` directory
142+
* Type hints in the code
143+
* The project README

‎docs/source/conf.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
import os
7+
import sys
8+
sys.path.insert(0, os.path.abspath('../..'))
9+
10+
# -- Project information -----------------------------------------------------
11+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
12+
13+
project = 'httpmorph'
14+
copyright = '2025, httpmorph contributors'
15+
author = 'httpmorph contributors'
16+
release = '0.1.3'
17+
18+
# -- General configuration ---------------------------------------------------
19+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
20+
21+
extensions = [
22+
'sphinx.ext.autodoc',
23+
'sphinx.ext.viewcode',
24+
'sphinx.ext.napoleon',
25+
'myst_parser',
26+
]
27+
28+
templates_path = ['_templates']
29+
exclude_patterns = []
30+
31+
# -- Options for HTML output -------------------------------------------------
32+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
33+
34+
html_theme = 'sphinx_rtd_theme'
35+
html_static_path = ['_static']
36+
37+
# -- Options for autodoc -----------------------------------------------------
38+
autodoc_member_order = 'bysource'
39+
autodoc_typehints = 'description'

0 commit comments

Comments
 (0)