689 Update documentation and add add release checklist (#691)

Author: arthanson

.github/workflows/build-mkdocs.yml

@@ -0,0 +1,18 @@
+name: Build MkDocs
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material mkdocs-autorefs mkdocs-material-extensions mkdocstrings mkdocstrings-python-legacy mkdocs-include-markdown-plugin pymdown-extensions markdown-include
+      - run: mkdocs gh-deploy --force

README.md

@@ -28,7 +28,7 @@ Alternatively, you can clone the repo and run `python setup.py install`.
 
 ## Quick Start
 
-The full pynetbox API is documented on [Read the Docs](http://pynetbox.readthedocs.io/en/latest/), but the following should be enough to get started using it.
+The full pynetbox API is documented on [GitHub Pages](https://netbox-community.github.io/pynetbox/), but the following should be enough to get started using it.
 
 To begin, import pynetbox and instantiate the API.
 

docs/IPAM.md

@@ -0,0 +1,11 @@
+# IPAM
+
+::: pynetbox.models.ipam.Prefixes
+    handler: python
+    options:
+        members: true
+
+::: pynetbox.models.ipam.VlanGroups
+    handler: python
+    options:
+        members: true 

docs/IPAM.rst

@@ -0,0 +1,69 @@
+# Custom Sessions
+
+Custom sessions can be used to modify the default HTTP behavior. Below are a few examples, most of them from [here](https://hodovi.ch/blog/advanced-usage-python-requests-timeouts-retries-hooks/).
+
+## Headers
+
+To set a custom header on all requests. These headers are automatically merged with headers pynetbox sets itself.
+
+Example:
+
+```python
+import pynetbox
+import requests
+session = requests.Session()
+session.headers = {"mycustomheader": "test"}
+nb = pynetbox.api(
+    'http://localhost:8000',
+    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+)
+nb.http_session = session
+```
+
+## SSL Verification
+
+To disable SSL verification. See [the docs](https://requests.readthedocs.io/en/stable/user/advanced/#ssl-cert-verification).
+
+Example:
+
+```python
+import pynetbox
+import requests
+session = requests.Session()
+session.verify = False
+nb = pynetbox.api(
+    'http://localhost:8000',
+    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+)
+nb.http_session = session
+```
+
+## Timeouts
+
+Setting timeouts requires the use of Adapters.
+
+Example:
+
+```python
+from requests.adapters import HTTPAdapter
+
+class TimeoutHTTPAdapter(HTTPAdapter):
+    def __init__(self, *args, **kwargs):
+        self.timeout = kwargs.get("timeout", 5)
+        super().__init__(*args, **kwargs)
+
+    def send(self, request, **kwargs):
+        kwargs['timeout'] = self.timeout
+        return super().send(request, **kwargs)
+
+adapter = TimeoutHTTPAdapter()
+session = requests.Session()
+session.mount("http://", adapter)
+session.mount("https://", adapter)
+
+nb = pynetbox.api(
+    'http://localhost:8000',
+    token='d6f4e314a5b5fefd164995169f28ae32d987704f'
+)
+nb.http_session = session
+``` 

docs/Makefile

@@ -0,0 +1,77 @@
+# Branching Plugin
+
+The NetBox branching plugin allows you to create and work with branches in NetBox, similar to version control systems. This enables you to make changes in isolation and merge them back to the main branch when ready.
+
+## Activating Branches
+
+The `activate_branch` context manager allows you to perform operations within a specific branch's schema. All operations performed within the context manager will use that branch's schema.
+
+```python
+import pynetbox
+
+# Initialize the API
+nb = pynetbox.api(
+    "http://localhost:8000",
+    token="your-token-here"
+)
+
+# Get an existing branch
+branch = nb.plugins.branching.branches.get(id=1)
+
+# Activate the branch for operations
+with nb.activate_branch(branch):
+    # All operations within this block will use the branch's schema
+    sites = nb.dcim.sites.all()
+    # Make changes to objects...
+    # These changes will only exist in this branch
+```
+
+## Waiting for Branch Status
+
+When working with branches, you often need to wait for certain status changes, such as when a branch becomes ready after creation or when a merge operation completes. The [tenacity](https://github.com/jd/tenacity) library provides a robust way to handle these waiting scenarios.
+
+First, install tenacity:
+
+```bash
+pip install tenacity
+```
+
+Here's how to create a reusable function to wait for branch status changes:
+
+```python
+from tenacity import retry, retry_if_result, stop_after_attempt, wait_exponential
+import pynetbox
+
+@retry(
+    stop=stop_after_attempt(30),  # Try for up to 30 attempts
+    wait=wait_exponential(
+        multiplier=1, min=4, max=60
+    ),  # Wait between 4-60 seconds, increasing exponentially
+    retry=retry_if_result(lambda x: not x),  # Retry if the status check returns False
+)
+def wait_for_branch_status(branch, target_status):
+    """Wait for branch to reach a specific status, with exponential backoff."""
+    branch = nb.plugins.branching.branches.get(branch.id)
+    return str(branch.status) == target_status
+
+# Example usage:
+branch = nb.plugins.branching.branches.create(name="my-branch")
+
+# Wait for branch to be ready
+wait_for_branch_status(branch, "Ready")
+
+# Get the latest branch status
+branch = nb.plugins.branching.branches.get(branch.id)
+print(f"Branch is now ready! Status: {branch.status}")
+```
+
+The function will:
+
+1. Check the current status of the branch
+2. If the status doesn't match the target status, it will retry with exponential backoff
+3. Continue retrying until either:
+    - The branch reaches the target status
+    - The maximum number of attempts (30) is reached
+    - The maximum wait time (60 seconds) is exceeded
+
+The exponential backoff ensures that we don't overwhelm the server with requests while still checking frequently enough to catch status changes quickly.