Basic docs skeleton.

.gitignore

@@ -15,6 +15,7 @@ env/
 bin/
 build/
 develop-eggs/
+dirhtml/
 dist/
 eggs/
 lib/

.readthedocs.yml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+formats: all
+
+python:
+  install:
+    - requirements: docs/requirements.txt

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "url-py"
-version = "0.3.1"
+version = "0.3.2"
 edition = "2021"
 
 [lib]

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     = .
+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/api.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. automodule:: url
+   :members:
+   :undoc-members:
+   :imported-members:

docs/changes.rst

@@ -0,0 +1,8 @@
+=========
+Changelog
+=========
+
+v0.3.2
+-------
+
+* Initial functional release with docs.

docs/compatibility.rst

@@ -0,0 +1,28 @@
+=============
+Compatibility
+=============
+
+``url.py`` is currently in beta so long as version numbers begin with a ``0``, meaning its public interface may change if issues are uncovered, though not typically without reason.
+Once it seems clear that the interfaces look correct (likely after ``url.py`` is in use for some period of time) versioning will move to `CalVer <https://calver.org/>`_ and interfaces will not change in backwards-incompatible ways without deprecation periods.
+
+.. note::
+
+    Backwards compatibility is always defined relative to the URL specifications implemented by our underlying library (the ``url`` crate).
+    Changing a behavior which is explicitly incorrect according to the relevant specifications is not considered a backwards-incompatible change -- on the contrary, it's considered a bug fix.
+
+In the spirit of `having some explicit detail on url.py's public interfaces <regret:before-you-deprecate:document your public api>`, here is a non-exhaustive list of things which are *not* part of the ``url.py`` public interface, and therefore which may change without warning, even once no longer in beta:
+
+* All commonly understood indicators of privacy in Python -- in particular, (sub)packages, modules and identifiers beginning with a single underscore.
+  In the case of modules or packages, this includes *all* of their contents recursively, regardless of their naming.
+* All contents in the ``tests`` package unless explicitly indicated otherwise
+* The precise contents and wording of exception messages raised by any callable, private *or* public.
+* The precise contents of the ``__repr__`` of any type defined in the package.
+* The ability to *instantiate* exceptions defined anywhere in the package, with the sole exception of those explicitly indicating they are publicly instantiable.
+* The instantiation of any type with no public identifier, even if instances of it are returned by other public API.
+* The concrete types within the signature of a callable whenever they differ from their documented types.
+  In other words, if a function documents that it returns an argument of type ``Mapping[int, Sequence[str]]``, this is the promised return type, not whatever concrete type is returned which may be richer or have additional attributes and methods.
+  Changes to the signature will continue to guarantee this return type (or a broader one) but indeed are free to change the concrete type.
+* Subclassing of any class defined throughout the package.
+  Doing so is not supported for any object.
+
+If any API usage may be questionable, feel free to open a discussion (or issue if appropriate) to clarify.

docs/conf.py

@@ -0,0 +1,82 @@
+import importlib.metadata
+import re
+
+from url import URL
+
+GITHUB = URL.parse("https://github.com/")
+HOMEPAGE = GITHUB.join("crate-py/url")
+
+project = "url-py"
+author = "Julian Berman"
+copyright = f"2023, {author}"
+
+release = importlib.metadata.version("url-py")
+version = release.partition("-")[0]
+
+language = "en"
+default_role = "any"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinxcontrib.spelling",
+    "sphinxext.opengraph",
+]
+
+pygments_style = "lovelace"
+pygments_dark_style = "one-dark"
+
+html_theme = "furo"
+
+
+def entire_domain(host):
+    return r"http.?://" + re.escape(host) + r"($|/.*)"
+
+
+linkcheck_ignore = [
+    entire_domain("img.shields.io"),
+    f"{GITHUB}.*#.*",
+    str(HOMEPAGE.join("actions")),
+    str(HOMEPAGE.join("workflows/CI/badge.svg")),
+]
+
+# = Extensions =
+
+# -- autodoc --
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+}
+
+# -- autosectionlabel --
+
+autosectionlabel_prefix_document = True
+
+# -- intersphinx --
+
+intersphinx_mapping = {
+    "regret": ("https://regret.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/", None),
+}
+
+# -- extlinks --
+
+extlinks = {
+    "gh": (str(HOMEPAGE) + "/%s", None),
+    "github": (str(GITHUB) + "/%s", None),
+}
+extlinks_detect_hardcoded_links = True
+
+# -- sphinxcontrib-spelling --
+
+spelling_word_list_filename = "spelling-wordlist.txt"
+spelling_show_suggestions = True

docs/index.rst

@@ -0,0 +1,9 @@
+Python bindings to the `Rust url crate <https://docs.rs/url/>`_.
+
+.. toctree::
+    :glob:
+    :hidden:
+
+    compatibility
+    api
+    changes

docs/requirements.in

@@ -0,0 +1,7 @@
+file:.#egg=url-py
+furo
+pygments-github-lexers
+sphinx-copybutton
+sphinx>5
+sphinxcontrib-spelling>5
+sphinxext-opengraph

docs/requirements.txt

@@ -0,0 +1,106 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile --strip-extras docs/requirements.in
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.13.0
+    # via sphinx
+beautifulsoup4==4.12.2
+    # via furo
+certifi==2023.7.22
+    # via requests
+charset-normalizer==3.3.0
+    # via requests
+contourpy==1.1.1
+    # via matplotlib
+cycler==0.12.1
+    # via matplotlib
+docutils==0.20.1
+    # via sphinx
+fonttools==4.43.1
+    # via matplotlib
+furo==2023.9.10
+    # via -r docs/requirements.in
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via sphinx
+kiwisolver==1.4.5
+    # via matplotlib
+markupsafe==2.1.3
+    # via jinja2
+matplotlib==3.8.0
+    # via sphinxext-opengraph
+numpy==1.26.1
+    # via
+    #   contourpy
+    #   matplotlib
+packaging==23.2
+    # via
+    #   matplotlib
+    #   sphinx
+pillow==10.1.0
+    # via matplotlib
+pyenchant==3.2.2
+    # via sphinxcontrib-spelling
+pygments==2.16.1
+    # via
+    #   furo
+    #   pygments-github-lexers
+    #   sphinx
+pygments-github-lexers==0.0.5
+    # via -r docs/requirements.in
+pyparsing==3.1.1
+    # via matplotlib
+python-dateutil==2.8.2
+    # via matplotlib
+requests==2.31.0
+    # via sphinx
+six==1.16.0
+    # via python-dateutil
+snowballstemmer==2.2.0
+    # via sphinx
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==7.2.6
+    # via
+    #   -r docs/requirements.in
+    #   furo
+    #   sphinx-basic-ng
+    #   sphinx-copybutton
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+    #   sphinxcontrib-spelling
+    #   sphinxext-opengraph
+sphinx-basic-ng==1.0.0b2
+    # via furo
+sphinx-copybutton==0.5.2
+    # via -r docs/requirements.in
+sphinxcontrib-applehelp==1.0.7
+    # via sphinx
+sphinxcontrib-devhelp==1.0.5
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.4
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.6
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.9
+    # via sphinx
+sphinxcontrib-spelling==8.0.0
+    # via -r docs/requirements.in
+sphinxext-opengraph==0.8.2
+    # via -r docs/requirements.in
+file:.#egg=url-py
+    # via -r docs/requirements.in
+urllib3==2.0.7
+    # via requests

docs/spelling-wordlist.txt

@@ -0,0 +1,5 @@
+changelog
+instantiable
+instantiation
+iterable
+subclassing