docs: Prepare for readthedocs

Author: defnull

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+   os: ubuntu-22.04
+   tools:
+     python: "3.12"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

Makefile

@@ -1,11 +1,11 @@
 VENV = build/venv
 
 venv: $(VENV)/.installed
-$(VENV)/.installed: Makefile
+$(VENV)/.installed: Makefile pyproject.toml
 	python3 -mvenv $(VENV)
 	$(VENV)/bin/python3 -m ensurepip
 	$(VENV)/bin/pip install -q -U pip
-	$(VENV)/bin/pip install -q -e .[dev]
+	$(VENV)/bin/pip install -q -e .[dev,docs]
 	touch $(VENV)/.installed
 
 build: venv
@@ -19,5 +19,9 @@ test: venv
 coverage: venv
 	$(VENV)/bin/pytest . -q --cov=multipart --cov-branch --cov-report=term --cov-report=html:build/htmlcov
 
+.PHONY: docs
+docs: venv
+	cd docs; ../$(VENV)/bin/sphinx-build -M html . ../build/docs  
+
 upload: build
 	$(VENV)/bin/python3 -m twine upload --skip-existing dist/multipart-*

docs/api.rst

@@ -0,0 +1,53 @@
+=============
+API Reference
+=============
+
+.. py:currentmodule:: multipart
+
+SansIO Parser
+=============
+
+.. autoclass:: PushMultipartParser
+    :members:
+
+.. autoclass:: MultipartSegment
+    :members:
+
+Stream Parser
+=============
+
+.. autoclass:: MultipartParser
+    :members:
+
+.. autoclass:: MultipartPart
+    :members:
+
+WSGI Helper
+===========
+
+.. autofunction:: is_form_request
+.. autofunction:: parse_form_data
+
+Header utils
+============
+
+.. autofunction:: parse_options_header
+.. autofunction:: header_quote
+.. autofunction:: header_unquote 
+.. autofunction:: content_disposition_quote
+.. autofunction:: content_disposition_unquote
+
+
+Exceptions
+==========
+
+
+.. autoexception:: MultipartError
+
+.. autoexception:: ParserError
+
+.. autoexception:: StrictParserError
+
+.. autoexception:: ParserLimitReached
+
+.. autoexception:: ParserStateError

docs/changelog.rst

@@ -0,0 +1,2 @@
+.. py:currentmodule:: multipart
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -0,0 +1,66 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Multipart"
+copyright = "2010-%Y, Marcel Hellkamp"
+author = "Marcel Hellkamp"
+
+
+# -- General configuration ---------------------------------------------------
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+]
+
+intersphinx_mapping = {
+    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+#templates_path = ["_templates"]
+
+# -- Options for EPUB output
+epub_show_urls = "footnote"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ["_static"]
+
+autoclass_content = 'both'
+autodoc_member_order = 'bysource'

docs/index.rst

@@ -0,0 +1,9 @@
+.. py:currentmodule:: multipart
+.. include:: ../README.rst
+
+.. toctree::
+    :maxdepth: 2
+
+    Home <self>
+    api
+    changelog

multipart.py

@@ -917,7 +917,7 @@ def parse_form_data(
             results may be empty or incomplete. If False, then exceptions are
             not suppressed. A value of None (default) throws exceptions in
             strict mode but suppresses errors in non-strict mode.
-        :param **kwargs: Additional keyword arguments are forwarded to
+        :param kwargs: Additional keyword arguments are forwarded to
             :class:`MultipartParser`. This is particularly useful to change the
             default parser limits.
         :raises MultipartError: See `ignore_errors` parameters. 

pyproject.toml

@@ -39,6 +39,10 @@ dev = [
     "build",
     "twine",
 ]
+docs = [
+    "Sphinx>=8,<9",
+    "sphinx_rtd_theme"
+]
 
 [tool.flit.sdist]
 include = [