Merge pull request #327 from prkumar/migrate-to-mkdocs

Migrate our docs to mkdocs

Author: prkumar

.gitignore

@@ -61,11 +61,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/source/.doctrees/
-docs/source/_build/
-docs/_build/
-
 # PyBuilder
 target/
 
@@ -96,7 +91,9 @@ ENV/
 .ropeproject
 
 # mkdocs documentation
+/docs/changelog.md
 /site
+/site.zip
 
 # mypy
 .mypy_cache/

CONTRIBUTING.md

@@ -25,7 +25,7 @@ uv sync --all-extras
 uv tool install pre-commit --with pre-commit-uv --force-reinstall
 ```
 
-If you are unfamiliar with [pipenv](https://docs.pipenv.org/) but are comfortable with [virtualenvs](https://virtualenv.pypa.io/en/stable/), you can alternatively run `pip install pipenv` inside the virtualenv you are already using then invoke the commands from above. This will setup your virtualenv correctly.
+If you are unfamiliar with [uv](https://github.com/astral-sh/uv) but are comfortable with [virtualenvs](https://virtualenv.pypa.io/en/stable/), you can alternatively run `pip install uv` inside the virtualenv you are already using then invoke the commands from above. This will setup your virtualenv correctly.
 
 Before submitting a pull request, run all tests with [tox](https://tox.readthedocs.io/en/latest/):
 
@@ -168,6 +168,4 @@ assert {"id": 123, "username": "prkumar"} == response.json()
 
 ## Style Guide
 
-To maintain a consistent code style with the rest of Uplink, follow the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
-
-Notably, we use a Sphinx plugin that can parse docstrings adherent to this style. Checkout [this page](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for examples of Google Python Style Guide docstrings.
+To maintain a consistent code style with the rest of Uplink, follow the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).

Pipfile

@@ -75,13 +75,11 @@ Ready to launch your first API client with Uplink? Start with this [quick tutori
   - Built-in support for [Basic Authentication](https://uplink.readthedocs.io/en/latest/user/auth.html#basic-authentication)
   - Use existing auth libraries for supported clients (e.g., [`requests-oauthlib`](https://github.com/requests/requests-oauthlib))
 
-Uplink officially supports Python 2.7 and 3.5+.
-
-**Note:** Python 2.7 support will be removed in v0.10.0.
+Uplink officially supports Python 3.10+.
 
 ## Installation
 
-To install the latest stable release, you can use `pip` (or `pipenv`):
+To install the latest stable release, you can use `pip` (or `uv`):
 
 ```bash
 pip install -U uplink
@@ -135,3 +133,4 @@ We're migrating our community from [Gitter](https://gitter.im/python-uplink/Lobb
 
 Want to report a bug, request a feature, or contribute code to Uplink? Checkout the [Contribution Guide](https://github.com/prkumar/uplink/blob/master/CONTRIBUTING.md) for where to start.
 Thank you for taking the time to improve an open source project 💜
+

README.md

@@ -0,0 +1,39 @@
+# Authentication
+
+The `auth` parameter of the `Consumer` constructor offers a way to
+define an auth method to use for all requests.
+
+``` python
+auth_method = SomeAuthMethod(...)
+github = GitHub(BASE_URL, auth=auth_method)
+```
+
+::: uplink.auth.BasicAuth
+    options:
+        show_bases: false
+        members: false
+        inherited_members: false
+
+::: uplink.auth.ProxyAuth
+    options:
+        show_bases: false
+        members: false
+        inherited_members: false
+
+::: uplink.auth.BearerToken
+    options:
+        show_bases: false
+        members: false
+        inherited_members: false
+
+::: uplink.auth.MultiAuth
+    options:
+        show_bases: false
+        members: false
+        inherited_members: false
+
+::: uplink.auth.ApiTokenParam
+    options:
+        show_bases: false
+        members: false
+        inherited_members: false

docs/Makefile

@@ -0,0 +1,29 @@
+# HTTP Clients
+
+The `client` parameter of the `Consumer` constructor offers a way
+to swap out Requests with another HTTP client, including those listed here:
+
+```python
+github = GitHub(BASE_URL, client=...)
+```
+
+## Requests
+
+::: uplink.RequestsClient
+    options:
+        members: false
+        inherited_members: false
+
+## Aiohttp
+
+::: uplink.AiohttpClient
+    options:
+        members: false
+        inherited_members: false
+
+## Twisted
+
+::: uplink.TwistedClient
+    options:
+        members: false
+        inherited_members: false

docs/api/auth.md

@@ -0,0 +1,22 @@
+# The Base Consumer Class
+
+## Consumer
+
+::: uplink.Consumer
+    options:
+        members:
+            - exceptions
+            - session
+        inherited_members: false
+
+## Session
+
+::: uplink.session.Session
+    options:
+        members:
+            - auth
+            - base_url
+            - context
+            - headers
+            - inject
+            - params

docs/api/clients.md

@@ -0,0 +1,103 @@
+# Converters
+
+The `converter` parameter of the `uplink.Consumer` constructor accepts a custom adapter class that handles serialization of HTTP request properties and deserialization of HTTP response objects:
+
+```python
+github = GitHub(BASE_URL, converter=...)
+```
+
+Starting with version v0.5, some out-of-the-box converters are included automatically and don't need to be explicitly provided through the `converter` parameter. These implementations are detailed below.
+
+## Marshmallow
+
+Uplink comes with optional support for `marshmallow`.
+
+::: uplink.converters.MarshmallowConverter
+    options:
+      members: false
+      inherited_members: false
+
+!!! note
+    Starting with version v0.5, this converter factory is automatically included if you have `marshmallow` installed, so you don't need to provide it when constructing your consumer instances.
+
+## Pydantic
+
+!!! info "New in version v0.9.2"
+    Uplink comes with optional support for `pydantic`.
+
+::: uplink.converters.PydanticConverter
+    options:
+      members: false
+      inherited_members: false
+
+!!! note
+    Starting with version v0.9.2, this converter factory is automatically included if you have `pydantic` installed, so you don't need to provide it when constructing your consumer instances.
+
+## Converting Collections
+
+!!! info "New in version v0.5.0"
+    Uplink can convert collections of a type, such as deserializing a response body into a list of users. If you have `typing` installed (the module is part of the standard library starting Python 3.5), you can use type hints (see [PEP 484](https://www.python.org/dev/peps/pep-0484/)) to specify such conversions. You can also leverage this feature without `typing` by using one of the proxy types defined in `uplink.types`.
+
+The following converter factory implements this feature and is automatically included, so you don't need to provide it when constructing your consumer instance:
+
+::: uplink.converters.TypingConverter
+    options:
+      members: false
+      inherited_members: false
+
+Here are the collection types defined in `uplink.types`. You can use these or the corresponding type hints from `typing` to leverage this feature:
+
+::: uplink.types.List
+    options:
+      show_bases: false
+      members: false
+      inherited_members: false
+
+::: uplink.types.Dict
+    options:
+      show_bases: false
+      members: false
+      inherited_members: false
+
+## Writing Custom JSON Converters
+
+As a shorthand, you can define custom JSON converters using the `@loads.from_json` (deserialization) and `@dumps.to_json` (serialization) decorators.
+
+These classes can be used as decorators to create converters of a class and its subclasses:
+
+```python
+# Creates a converter that can deserialize the given `json` in to an
+# instance of a `Model` subtype.
+@loads.from_json(Model)
+def load_model_from_json(model_type, json):
+    ...
+```
+
+!!! note
+    Unlike consumer methods, these functions should be defined outside of a class scope.
+
+To use the converter, provide the generated converter object when instantiating a `uplink.Consumer` subclass, through the `converter` constructor parameter:
+
+```python
+github = GitHub(BASE_URL, converter=load_model_from_json)
+```
+
+Alternatively, you can add the `@install` decorator to register the converter function as a default converter, meaning the converter will be included automatically with any consumer instance and doesn't need to be explicitly provided through the `converter` parameter:
+
+```python
+from uplink import install, loads
+
+# Register the function as a default loader for the given model class.
+@install
+@loads.from_json(Model)
+def load_model_from_json(model_type, json):
+    ...
+```
+
+::: uplink.loads
+    options:
+      members: ["from_json"]
+
+::: uplink.dumps
+    options:
+      ffmembers: ["to_json"]