### Install django-sphinx-hosting package

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Instructions for installing the package via pip and running the built-in test suite to verify the installation.

```bash
pip install django-sphinx-hosting
python -m unittest discover
```

--------------------------------

### GET /api/v1/pages/

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

List and search documentation pages with support for filtering by version, title, or project.

```APIDOC
## GET /api/v1/pages/

### Description
Query documentation pages based on specific criteria like version or title.

### Method
GET

### Endpoint
/api/v1/pages/

### Parameters
#### Query Parameters
- **version** (integer) - Optional - Filter by version ID.
- **title** (string) - Optional - Filter by page title.
- **project_machine_name** (string) - Optional - Filter by project machine name.

### Response
#### Success Response (200)
- **count** (integer) - Number of results
- **results** (array) - List of page objects

#### Response Example
{
    "count": 1,
    "results": [
        {
            "id": 101,
            "title": "Installation Guide",
            "relative_path": "installation"
        }
    ]
}
```

--------------------------------

### Example API Request using cURL with Token Authentication

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/api.rst

This cURL command demonstrates how to make a GET request to the django-sphinx-hosting API. It includes setting the Accept header for JSON output, the Authorization header with a provided token, and other options for verbose output and insecure connection.

```bash
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token __THE_TOKEN__' \
    --insecure \
    --verbose \
    https://localhost/api/v1/projects/
```

--------------------------------

### Example Host-Project Builder Implementation (Python)

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/project_detail_customization.rst

An example of a host-project builder function that appends a custom CardWidget to the main content area and adds a link button and a form button to the sidebar using the WidgetListLayout API.

```python
# myproject/core/wildewidgets.py
from wildewidgets import Block, CardWidget

def extend_project_detail_layout(*, request, user, project, layout, view) -> None:
   del request, user, view
   layout.add_widget(
      CardWidget(
         title="Ecosystem Integrations",
         icon="boxes",
         widget=Block(
            f"Extra project-specific details for {project.title} can go here."
         ),
      )
   )
   layout.add_sidebar_link_button(
      "Support Runbook",
      f"/support/projects/{project.machine_name}/",
      color="teal",
   )
   layout.add_sidebar_form_button(
      "Sync Metadata",
      "/integrations/sync-project/",
      color="outline-primary",
      data={"project": project.pk},
   )

```

--------------------------------

### Get Project's Latest Version (API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Retrieve the most recent version of a specific project using the API. This requires an authorization token and the project ID. The response includes details about the version, Sphinx version, and associated content.

```bash
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    https://sphinx-hosting.example.com/api/v1/projects/1/latest_version/
```

--------------------------------

### GET /api/v1/projects/{id}/latest_version/

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Retrieves the latest version details for a specific project identified by its ID.

```APIDOC
## GET /api/v1/projects/{id}/latest_version/

### Description
Fetch the most recent version of documentation for a given project.

### Method
GET

### Endpoint
/api/v1/projects/{id}/latest_version/

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **url** (string) - API URL of the version
- **id** (integer) - Version ID
- **version** (string) - Version string (e.g., "2.0.0")

#### Response Example
{
    "url": "https://localhost/api/v1/versions/5/",
    "id": 5,
    "project": "https://localhost/api/v1/projects/1/",
    "version": "2.0.0",
    "sphinx_version": "7.2.6"
}
```

--------------------------------

### Configure Django REST Framework for Token Authentication

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/api.rst

This Python code snippet demonstrates how to configure Django settings for the REST Framework to enable Token Authentication. It includes necessary app installations and default parser/filter backends required for the API to function.

```python
INSTALLED_APPS = [
    ...
    'rest_framework.authtoken',
    ...
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': ('rest_framework.authentication.TokenAuthentication',),
    # https://www.django-rest-framework.org/api-guide/parsers/#setting-the-parsers
    'DEFAULT_PARSER_CLASSES': ('rest_framework.parsers.JSONParser',),
    # https://django-filter.readthedocs.io/en/master/guide/rest_framework.html
    'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',),
}
```

--------------------------------

### Create Project

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Create a new documentation project with title, machine_name, and optional description.

```APIDOC
## Create Project

### Description
Create a new documentation project with title, machine_name, and optional description.

### Method
POST

### Endpoint
/api/v1/projects/

### Parameters
#### Request Body
- **title** (string) - Required - The title of the project.
- **machine_name** (string) - Required - The machine-readable name of the project.
- **description** (string) - Optional - A description of the project.
- **classifiers** (array of objects) - Optional - A list of classifiers for the project.
  - **name** (string) - Required - The name of the classifier.

### Request Example
```bash
curl -X POST \
    -H 'Accept: application/json; indent=4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    -d '{
        "title": "My New Project",
        "machine_name": "my-new-project",
        "description": "Documentation for my new project",
        "classifiers": [{"name": "Language :: Python"}]
    }' \
    https://sphinx-hosting.example.com/api/v1/projects/
```

### Response
#### Success Response (201 Created)
- **url** (string) - The API URL for the newly created project.
- **id** (integer) - The unique identifier for the project.
- **title** (string) - The title of the project.
- **machine_name** (string) - The machine-readable name of the project.
- **description** (string) - A description of the project.
- **related_links** (array) - A list of related links.
- **classifiers** (array) - A list of classifiers associated with the project.
  - **url** (string) - The API URL for the classifier.
  - **id** (integer) - The unique identifier for the classifier.
  - **name** (string) - The name of the classifier.
- **latest_version** (string or null) - The API URL for the latest version of the documentation, or null if no versions exist.
- **versions** (array) - A list of API URLs for all versions of the documentation.

#### Response Example
```json
{
    "url": "https://localhost/api/v1/projects/42/",
    "id": 42,
    "title": "My New Project",
    "machine_name": "my-new-project",
    "description": "Documentation for my new project",
    "related_links": [],
    "classifiers": [{"url": "...", "id": 1, "name": "Language :: Python"}],
    "latest_version": null,
    "versions": []
}
```
```

--------------------------------

### Create Project (REST API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Creates a new documentation project via the django-sphinx-hosting API. Requires 'Accept' and 'Content-Type' headers for JSON, and an 'Authorization' token. Accepts title, machine_name, and optional description and classifiers.

```bash
curl -X POST \
    -H 'Accept: application/json; indent=4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    -d '{
        "title": "My New Project",
        "machine_name": "my-new-project",
        "description": "Documentation for my new project",
        "classifiers": [{"name": "Language :: Python"}]
    }' \
    https://sphinx-hosting.example.com/api/v1/projects/

# Response:
{
    "url": "https://localhost/api/v1/projects/42/",
    "id": 42,
    "title": "My New Project",
    "machine_name": "my-new-project",
    "description": "Documentation for my new project",
    "related_links": [],
    "classifiers": [{"url": "...", "id": 1, "name": "Language :: Python"}],
    "latest_version": null,
    "versions": []
}
```

--------------------------------

### Building Documentation Packages (Bash)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Prepare Sphinx documentation for import by building it into a JSON format instead of the default HTML. This is achieved by running the 'make json' command within your Sphinx documentation directory. The resulting JSON package is suitable for programmatic import.

```bash
# In your Sphinx docs directory
cd docs

# Build as JSON instead of HTML
make json
```

--------------------------------

### Configure Django INSTALLED_APPS for sphinx-hosting

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Add the required dependencies and the sphinx_hosting application to the INSTALLED_APPS list in the Django settings file.

```python
INSTALLED_APPS = [
   'django.contrib.admin',
   'django.contrib.auth',
   'django.contrib.contenttypes',
   'django.contrib.messages',
   'django.contrib.sessions',
   'django.contrib.sites',

   'rest_framework',
   'rest_framework.authtoken',
   'django_filters',
   'drf_spectacular',
   'crispy_forms',
   'crispy_bootstrap5',
   'haystack',
   'academy_theme',
   'wildewidgets',
   'sphinx_hosting',
   'sphinx_hosting.api'
]
```

--------------------------------

### List Projects

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Retrieve all documentation projects with optional filtering by title, machine name, description, or classifier.

```APIDOC
## List Projects

### Description
Retrieve all documentation projects with optional filtering by title, machine name, description, or classifier.

### Method
GET

### Endpoint
/api/v1/projects/

### Parameters
#### Query Parameters
- **title** (string) - Optional - Filter by project title (case insensitive, partial match).
- **machine_name** (string) - Optional - Filter by project machine name.
- **description** (string) - Optional - Filter by project description.
- **classifier** (string) - Optional - Filter by project classifier.

### Request Example
```bash
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    https://sphinx-hosting.example.com/api/v1/projects/

# Filter by title (case insensitive, partial match)
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/projects/?title=my-lib'
```

### Response
#### Success Response (200)
- **count** (integer) - The total number of projects.
- **next** (string) - URL for the next page of results.
- **previous** (string) - URL for the previous page of results.
- **results** (array) - A list of project objects.
  - **url** (string) - The API URL for the project.
  - **id** (integer) - The unique identifier for the project.
  - **title** (string) - The title of the project.
  - **machine_name** (string) - The machine-readable name of the project.
  - **description** (string) - A description of the project.
  - **related_links** (array) - A list of related links.
  - **classifiers** (array) - A list of classifiers associated with the project.
    - **url** (string) - The API URL for the classifier.
    - **id** (integer) - The unique identifier for the classifier.
    - **name** (string) - The name of the classifier.
  - **latest_version** (string) - The API URL for the latest version of the documentation.
  - **versions** (array) - A list of API URLs for all versions of the documentation.

#### Response Example
```json
{
    "count": 123,
    "next": "https://localhost/api/v1/projects/?limit=100&offset=100",
    "previous": null,
    "results": [
        {
            "url": "https://localhost/api/v1/projects/1/",
            "id": 1,
            "title": "My Library",
            "machine_name": "my-library",
            "description": "A Python utility library",
            "related_links": [],
            "classifiers": [
                {"url": "...", "id": 1, "name": "Language :: Python"}
            ],
            "latest_version": "https://localhost/api/v1/versions/5/",
            "versions": [
                "https://localhost/api/v1/versions/1/",
                "https://localhost/api/v1/versions/5/"
            ]
        }
    ]
}
```
```

--------------------------------

### List Projects (REST API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Retrieves all documentation projects from the django-sphinx-hosting API. Supports filtering by title, machine name, description, or classifier. Requires an 'Accept' header for JSON and an 'Authorization' token.

```bash
# List all projects
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    https://sphinx-hosting.example.com/api/v1/projects/

# Filter by title (case insensitive, partial match)
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/projects/?title=my-lib'

# Response example:
{
    "count": 123,
    "next": "https://localhost/api/v1/projects/?limit=100&offset=100",
    "previous": null,
    "results": [
        {
            "url": "https://localhost/api/v1/projects/1/",
            "id": 1,
            "title": "My Library",
            "machine_name": "my-library",
            "description": "A Python utility library",
            "related_links": [],
            "classifiers": [
                {"url": "...", "id": 1, "name": "Language :: Python"}
            ],
            "latest_version": "https://localhost/api/v1/versions/5/",
            "versions": [
                "https://localhost/api/v1/versions/1/",
                "https://localhost/api/v1/versions/5/"
            ]
        }
    ]
}
```

--------------------------------

### List and Search Pages (API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Query documentation pages by filtering through various parameters like version, title, or project. This API endpoint allows for flexible searching of documentation content. Requires an authorization token.

```bash
# List pages for a specific version
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/pages/?version=5'

# Search pages by title
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/pages/?title=installation&project_machine_name=my-library'
```

--------------------------------

### List Versions (REST API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Retrieves documentation versions from the django-sphinx-hosting API. Supports filtering by project machine name, version number, and archived status. Requires an 'Authorization' token.

```bash
# List all versions
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    https://sphinx-hosting.example.com/api/v1/versions/

# Filter by project and version number
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/versions/?project_machine_name=my-library&version_number=1.2.0'

# Filter by archived status
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/versions/?archived=false'
```

--------------------------------

### List Versions

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Retrieve documentation versions with comprehensive filtering options.

```APIDOC
## List Versions

### Description
Retrieve documentation versions with comprehensive filtering options.

### Method
GET

### Endpoint
/api/v1/versions/

### Parameters
#### Query Parameters
- **project_machine_name** (string) - Optional - Filter by the machine name of the project.
- **version_number** (string) - Optional - Filter by the specific version number.
- **archived** (boolean) - Optional - Filter by the archived status of the version (true/false).

### Request Example
```bash
# List all versions
curl -X GET \
    -H 'Accept: application/json; indent=4' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    https://sphinx-hosting.example.com/api/v1/versions/

# Filter by project and version number
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/versions/?project_machine_name=my-library&version_number=1.2.0'

# Filter by archived status
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/versions/?archived=false'
```

### Response
#### Success Response (200 OK)
- **count** (integer) - The total number of versions.
- **next** (string) - URL for the next page of results.
- **previous** (string) - URL for the previous page of results.
- **results** (array) - A list of version objects.
  - **url** (string) - The API URL for the version.
  - **id** (integer) - The unique identifier for the version.
  - **project** (string) - The API URL for the project this version belongs to.
  - **version_number** (string) - The version number.
  - **created** (string) - The date and time the version was created.
  - **modified** (string) - The date and time the version was last modified.
  - **archived** (boolean) - Whether the version is archived.
  - **documentation_file** (string) - The URL to the documentation tarball.
  - **search_index** (string) - The URL to the search index file.

#### Response Example
(Note: The example response structure for List Versions was not provided in the input text. This is a placeholder based on typical API patterns.)
```json
{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "url": "https://localhost/api/v1/versions/1/",
            "id": 1,
            "project": "https://localhost/api/v1/projects/1/",
            "version_number": "1.0.0",
            "created": "2023-01-01T10:00:00Z",
            "modified": "2023-01-01T10:00:00Z",
            "archived": false,
            "documentation_file": "/media/versions/1/docs.tar.gz",
            "search_index": "/media/versions/1/search_index.json"
        }
    ]
}
```
```

--------------------------------

### Configure SPHINX_HOSTING_SETTINGS

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Define the SPHINX_HOSTING_SETTINGS dictionary to customize branding, navigation, and version exclusion patterns for the documentation platform.

```python
SPHINX_HOSTING_SETTINGS = {
   'LOGO_IMAGE': 'core/images/my-org-logo.png',
   'LOGO_WIDTH': '75%',
   'LOGO_URL': 'https://www.example.com',
   'SITE_NAME': 'MyOrg Documentation',
   'EXCLUDE_FROM_LATEST': ['*.dev*', '*.beta*'],
   'EXTRA_MENU_ITEMS': [
      {
         'text': 'REST API',
         'icon': 'diagram-3',
         'url': '/api/v1/schema/swagger-ui/'
      }
   ],
   'MENU_ITEM_BUILDERS': ['myproject.core.navigation.build_menu_items'],
   'NAVBAR_CLASS': 'myproject.core.wildewidgets.MainMenu',
   'PROJECT_DETAIL_LAYOUT_BUILDERS': [
      'myproject.core.wildewidgets.extend_project_detail_layout',
   ],
}
```

--------------------------------

### Import Documentation Programmatically (Python)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Use the SphinxPackageImporter class from the sphinx_hosting library to import Sphinx documentation packages directly within Python scripts. This involves creating a Project instance first and then using the importer's run method with a filename or file object. The importer handles the extraction and storage of documentation content.

```python
from sphinx_hosting.importers import SphinxPackageImporter
from sphinx_hosting.models import Project, Version

# Create a project first (required before import)
project = Project.objects.create(
    title="My Library",
    machine_name="my-library",  # Must match 'project' in Sphinx conf.py
    description="Documentation for my library"
)

# Import documentation from a tarball file
importer = SphinxPackageImporter()
version = importer.run(filename="/path/to/docs.tar.gz", force=False)

print(f"Imported version: {version.version}")
print(f"Project: {version.project.title}")
print(f"Pages count: {version.pages.count()}")
print(f"Images count: {version.images.count()}")

# Force re-import (overwrites existing version)
version = importer.run(filename="/path/to/docs.tar.gz", force=True)

# Import from a file object
with open("/path/to/docs.tar.gz", "rb") as f:
    version = SphinxPackageImporter().run(file_obj=f, force=True)
```

--------------------------------

### POST /api/v1/classifiers/

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Create new project classification tags to organize and filter documentation projects.

```APIDOC
## POST /api/v1/classifiers/

### Description
Create a new classifier. Supports hierarchical naming using '::' syntax.

### Method
POST

### Endpoint
/api/v1/classifiers/

### Parameters
#### Request Body
- **name** (string) - Required - The classifier name (e.g., "Ecosystem :: CMS :: Django")

### Response
#### Success Response (201)
- **id** (integer) - Created classifier ID
- **name** (string) - Classifier name

#### Response Example
{
    "id": 10,
    "name": "Ecosystem :: CMS :: Django"
}
```

--------------------------------

### Build Sphinx Documentation to JSON

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Builds Sphinx documentation into JSON format using the `sphinx-build` command. The output is organized in a specific tarball structure required for hosting.

```bash
sphinx-build -n -b json source build/json

cd build
tar zcf mydocs.tar.gz json
```

--------------------------------

### Configure DRF-Spectacular Settings

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Defines the schema path prefix, server details, and metadata for the DRF-Spectacular API documentation generator. This configuration ensures the API documentation correctly reflects the project's version and description.

```python
SPECTACULAR_SETTINGS = {
	'SCHEMA_PATH_PREFIX': r'/api/v1',
	'SERVERS': [
		{
			'url': 'https://localhost',
			'description': 'Django Sphinx Hosting'
		}
	],
	'TITLE': 'YOUR_SITE_NAME',
	'VERSION': __version__,
	'DESCRIPTION': """__YOUR_DESCRIPTION__HERE"""
}
```

--------------------------------

### Configure Django Wildewidgets, Theme Academy, and Crispy Forms

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Sets up the default template pack for django-crispy-forms, configures the django-theme-academy with various assets and links, and defines the datetime format for django-wildewidgets. These settings are crucial for rendering HTML content and structuring the site's appearance.

```python
# crispy-forms
# ------------------------------------------------------------------------------
CRISPY_ALLOWED_TEMPLATE_PACKS = 'bootstrap5'
CRISPY_TEMPLATE_PACK = 'bootstrap5'

# django-theme-academy
# ------------------------------------------------------------------------------
ACADEMY_THEME_SETTINGS = {
   # Header
   'APPLE_TOUCH_ICON': 'core/images/apple-touch-icon.png',
   'FAVICON_32': 'core/images/favicon-32x32.png',
   'FAVICON_16': 'core/images/favicon-16x16.png',
   'FAVICON': 'core/images/favicon.ico',
   'SITE_WEBMANIFEST': 'core/images/site.webmanifest',

   # Footer
   'ORGANIZATION_LINK': 'https://github.com/caltechads/django-sphinx-hosting',
   'ORGANIZATION_NAME': 'Sphinx Hosting',
   'ORGANIZATION_ADDRESS': '123 Main Street, Everytown, ST',
   'COPYRIGHT_ORGANIZATION': 'Sphinx Hosting',
   'FOOTER_LINKS': [
      ('https://example.com', 'Organization Home'),
      ('https://example.com/documents/privacy.pdf', "Privacy Policy")
   ]
}

# django-wildewidgets
# ------------------------------------------------------------------------------
WILDEWIDGETS_DATETIME_FORMAT = "%Y-%m-%d %H:%M %Z"

```

--------------------------------

### Migrate Database and Create API Token

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/api.rst

These bash commands are used to manage the Django database and create API authentication tokens. The first command applies database migrations to create necessary models, and the second generates a token for a specified user.

```bash
python manage.py migrate
```

```bash
python manage.py drf_create_token <username>
```

--------------------------------

### Import Documentation with Django Management Command

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Imports documentation from a tarball using the `./manage.py import_docs` command. Supports basic import and forcing an overwrite of existing versions.

```bash
# Basic import
./manage.py import_docs /path/to/mydocs.tar.gz

# Force overwrite existing version
./manage.py import_docs --force /path/to/mydocs.tar.gz
```

--------------------------------

### Core Models Overview

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/api/models.rst

Documentation for the primary data models including Project, Version, and SphinxPage.

```APIDOC
## Models Overview

### Description
Defines the structure for managing documentation projects, their versions, and individual pages within the system.

### Models
- **Project**: Represents a hosted documentation project.
- **Version**: Represents a specific version (e.g., 'latest', 'v1.0') of a project.
- **SphinxPage**: Represents an individual HTML page generated by Sphinx.
- **Classifier**: Used for categorizing projects.

### Utility Classes
- **SphinxPageTree**: Handles the hierarchical structure of documentation pages.
- **SphinxPageTreeProcessor**: Logic for processing the page tree structure.
- **SphinxGlobalTOCHTMLProcessor**: Handles global Table of Contents generation.

### Utility Functions
- **sphinx_image_upload_to**: Helper function for determining image upload paths.
```

--------------------------------

### Sphinx Configuration: Basic Extensions and Theme

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/packaging.rst

This configuration snippet shows the essential Sphinx extensions and theme settings required by django-sphinx-hosting. It includes 'sphinx_rtd_theme' for consistent HTML structure and sets 'collapse_navigation' to False to ensure proper navigation rendering.

```python
extensions = [
    'sphinx_rtd_theme',
    ...
]

html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    "collapse_navigation": False
}
```

--------------------------------

### Upload Documentation Version (REST API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Uploads a Sphinx documentation tarball to create or update a version in django-sphinx-hosting. The tarball must be built with `sphinx-build -b json` and include `globalcontext.json`. Uses a POST request with an 'Authorization' token and a file upload.

```bash
# Upload documentation package via API
curl -X POST \
    -H "Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876" \
    -F 'file=@path/to/mydocs.tar.gz' \
    https://sphinx-hosting.example.com/api/v1/version/import/

# Success response:
{
    "status": "success",
    "version_id": 15,
    "project_id": 42
}

# Error response (project not found):
{
    "status": "error",
    "message": "Project matching query does not exist."
}
```

--------------------------------

### Configure Django URL Patterns

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Registers URL routes for Sphinx documentation, Wildewidgets dispatch, and API endpoints within the Django project's top-level urlconf. It utilizes include for modular routing and class-based views for specific functionality.

```python
from django.urls import path, include

from sphinx_hosting import urls as sphinx_hosting_urls
from sphinx_hosting.api import urls as sphinx_hosting_api_urls
from wildewidgets import WildewidgetDispatch

urlpatterns = [
	path('/docs/', include(sphinx_hosting_urls, namespace='sphinx_hosting')),
	path('/docs/wildewidgets_json', WildewidgetDispatch.as_view(), name='wildewidgets_json'),
	path('api/v1/', include(sphinx_hosting_api_urls, namespace='sphinx_hosting_api')),
]
```

--------------------------------

### Configure Haystack with OpenSearch Backend

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Sets up the Haystack search engine configuration to use OpenSearch as the default backend. This includes specifying the engine, the URL of the OpenSearch instance, and the index name to be used. This is essential for enabling search functionality within the documentation.

```python
HAYSTACK_CONNECTIONS = {
   'default': {
      'ENGINE': 'django_haystack_opensearch.haystack.OpenSearchSearchEngine',
      'URL': 'http://sphinx-hosting-search.example.com:9200/',
      'INDEX_NAME': 'sphinx_hosting',
   },
}

```

--------------------------------

### Create Tarball of JSON Docs

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/importing.rst

Creates a gzipped tar archive containing the Sphinx JSON documentation. The 'json' directory must be at the root of the tarball for correct import into django-sphinx-hosting. This command assumes you are in the 'build' directory.

```shell
cd build
tar zcf mydocs.tar.gz json
```

--------------------------------

### Upload Documentation Version

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Upload a Sphinx documentation tarball to create or update a version. The tarball must be built with `sphinx-build -b json` and contain a `globalcontext.json` file.

```APIDOC
## Upload Documentation Version

### Description
Upload a Sphinx documentation tarball to create or update a version. The tarball must be built with `sphinx-build -b json` and contain a `globalcontext.json` file.

### Method
POST

### Endpoint
/api/v1/version/import/

### Parameters
#### Request Body
- **file** (file) - Required - The Sphinx documentation tarball (e.g., `.tar.gz`).

### Request Example
```bash
# Upload documentation package via API
curl -X POST \
    -H "Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876" \
    -F 'file=@path/to/mydocs.tar.gz' \
    https://sphinx-hosting.example.com/api/v1/version/import/
```

### Response
#### Success Response (200 OK)
- **status** (string) - Indicates success ('success').
- **version_id** (integer) - The ID of the newly created or updated documentation version.
- **project_id** (integer) - The ID of the project to which the version belongs.

#### Error Response (e.g., 400 Bad Request, 404 Not Found)
- **status** (string) - Indicates an error ('error').
- **message** (string) - A description of the error.

#### Response Example (Success)
```json
{
    "status": "success",
    "version_id": 15,
    "project_id": 42
}
```

#### Response Example (Error - Project not found)
```json
{
    "status": "error",
    "message": "Project matching query does not exist."
}
```
```

--------------------------------

### Manage Classifiers (API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Create and manage classification tags for projects to enhance organization and filtering. This involves listing existing classifiers and creating new ones, potentially in a hierarchical format. Requires an authorization token.

```bash
# List classifiers
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    https://sphinx-hosting.example.com/api/v1/classifiers/

# Create a classifier (hierarchical format)
curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    -d '{"name": "Ecosystem :: CMS :: Django"}' \
    https://sphinx-hosting.example.com/api/v1/classifiers/
```

--------------------------------

### Django Project Model

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Defines the core `Project` model for representing documentation projects. Includes creation, classifier management, and accessing associated versions and URLs.

```python
from sphinx_hosting.models import Project, Classifier

# Create a project with classifiers
project = Project.objects.create(
    title="My Awesome Library",
    machine_name="my-awesome-library",
    description="A comprehensive Python utility library"
)

# Add classifiers
classifier = Classifier.objects.create(name="Language :: Python :: 3.11")
project.classifiers.add(classifier)

# Access versions
for version in project.versions.all():
    print(f"{version.version}: {version.pages.count()} pages")

# Get latest version
if project.latest_version:
    print(f"Latest: {project.latest_version.version}")
    print(f"Head page: {project.latest_version.head.title}")

# Get URLs
print(project.get_absolute_url())        # /project/my-awesome-library/
print(project.get_latest_version_url())  # /project/my-awesome-library/latest/index/
```

--------------------------------

### Configure Project Detail Layout Builders (Python)

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/project_detail_customization.rst

Configures the SPHINX_HOSTING_SETTINGS dictionary to specify which builder functions should be executed to extend the project detail page layout. The PROJECT_DETAIL_LAYOUT_BUILDERS key takes a list of dotted-path strings to callable functions.

```python
SPHINX_HOSTING_SETTINGS = {
   "PROJECT_DETAIL_LAYOUT_BUILDERS": [
      "myproject.core.wildewidgets.extend_project_detail_layout",
   ],
}

```

--------------------------------

### Django Settings Configuration for django-sphinx-hosting

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Configures `django-sphinx-hosting` within your Django project's `settings.py`. Includes `INSTALLED_APPS`, Django REST Framework settings, and specific `SPHINX_HOSTING_SETTINGS`.

```python
# settings.py

INSTALLED_APPS = [
    # Django apps
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    # ...

    # Required dependencies
    'rest_framework',
    'rest_framework.authtoken',
    'django_filters',
    'haystack',
    'crispy_forms',
    'crispy_bootstrap5',
    'wildewidgets',

    # The app
    'sphinx_hosting',
    'sphinx_hosting.api',
]

# Django REST Framework configuration
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework.authentication.TokenAuthentication',
    ),
    'DEFAULT_PARSER_CLASSES': (
        'rest_framework.parsers.JSONParser',
    ),
    'DEFAULT_FILTER_BACKENDS': (
        'django_filters.rest_framework.DjangoFilterBackend',
    ),
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 100,
}

# Sphinx Hosting Settings
SPHINX_HOSTING_SETTINGS = {
    'SITE_NAME': 'My Docs Portal',
    'LOGO_IMAGE': 'myapp/images/logo.png',
    'LOGO_URL': '/',
    'LOGO_WIDTH': '150px',
    'MAX_GLOBAL_TOC_TREE_DEPTH': 3,
    'EXCLUDE_FROM_LATEST': ['*-dev*', '*-alpha*', '*-beta*', '*-rc*'],
}
```

--------------------------------

### Project Widgets

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/api/widgets.rst

Widgets for project listing and details pages, including forms, tables, and modals.

```APIDOC
## Project Widgets

### Description
These widgets are utilized on project listing and details pages. They facilitate tasks such as filtering projects, displaying project information, and managing versions.

### Widgets
- ClassifierFilterForm
- ClassifierFilterBlock
- ProjectCreateModalWidget
- ProjectDetailWidget
- ProjectTableWidget
- ProjectVersionsTableWidget
- ProjectTable
- ProjectVersionTable
```

--------------------------------

### Manage Project Related Links (API)

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Add and manage external resource links associated with projects. This includes creating new links with a title, URI, and project association, as well as listing existing links for a project. Requires an authorization token.

```bash
# Create a related link
curl -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    -d '{ \
        "title": "GitHub Repository", \
        "uri": "https://github.com/org/my-project", \
        "project": "https://localhost/api/v1/projects/1/" \
    }' \
    https://sphinx-hosting.example.com/api/v1/related-links/

# List related links for a project
curl -X GET \
    -H 'Authorization: Token b422b0e7d1d11f5060613c01c4ccd1b00174b876' \
    'https://sphinx-hosting.example.com/api/v1/related-links/?project_machine_name=my-library'
```

--------------------------------

### Haystack Search Backend Configuration

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Configures the search backend for documentation indexing using Django Haystack. Supports file-based backends like Whoosh for development and production-ready backends like OpenSearch/Elasticsearch. Also enables automatic index updates.

```python
# settings.py

# Using Whoosh (file-based, good for development)
HAYSTACK_CONNECTIONS = {
    'default': {
        'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
        'PATH': '/path/to/whoosh_index',
    },
}

# Using OpenSearch/Elasticsearch (production)
HAYSTACK_CONNECTIONS = {
    'default': {
        'ENGINE': 'haystack.backends.elasticsearch7_backend.Elasticsearch7SearchEngine',
        'URL': 'http://localhost:9200/',
        'INDEX_NAME': 'sphinx_hosting',
    },
}

# Enable automatic index updates
HAYSTACK_SIGNAL_PROCESSOR = 'haystack.signals.RealtimeSignalProcessor'
```

--------------------------------

### Build Sphinx Docs as JSON

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/importing.rst

Builds Sphinx documentation into JSON format instead of HTML. This is a prerequisite for packaging the documentation for django-sphinx-hosting. Ensure your Sphinx project is configured correctly before running.

```shell
make json
```

```shell
sphinx-build -n -b json build/json
```

--------------------------------

### POST /api/v1/version/import/

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/importing.rst

Uploads a gzipped tarfile containing Sphinx documentation in JSON format to the hosting service.

```APIDOC
## POST /api/v1/version/import/

### Description
Uploads a pre-packaged Sphinx documentation archive (tar.gz) to the server. The request must be sent as multipart/form-data.

### Method
POST

### Endpoint
/api/v1/version/import/

### Parameters
#### Request Body
- **file** (file) - Required - The gzipped tarfile containing the Sphinx JSON documentation build.

### Request Example
```bash
curl -XPOST \
    -H "Authorization: Token __THE_API_TOKEN__" \
    -F 'file=@path/to/yourdocs.tar.gz' \
    https://sphinx-hosting.example.com/api/v1/version/import/
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation of successful import.

#### Response Example
{
  "status": "success",
  "message": "Documentation imported successfully."
}
```

--------------------------------

### Django Version Model

Source: https://context7.com/caltechads/django-sphinx-hosting/llms.txt

Represents a specific version of project documentation. Allows access to version properties, navigation of the page tree, global table of contents, and marking searchable pages.

```python
from sphinx_hosting.models import Version, SphinxPageTree

# Access version properties
version = project.versions.get(version="1.2.0")

print(f"Version: {version.version}")
print(f"Sphinx version: {version.sphinx_version}")
print(f"Is latest: {version.is_latest}")
print(f"Archived: {version.archived}")

# Navigate page tree
tree = version.page_tree  # SphinxPageTree instance
for page in tree.traverse():
    print(f"  {page.relative_path}: {page.title}")

# Get global table of contents structure
globaltoc = version.globaltoc
# Returns: {'items': [{'text': 'Home', 'url': '...', 'items': [...]}]}

# Mark searchable pages (called automatically on import)
version.mark_searchable_pages()
```

--------------------------------

### Class: SphinxPackageImporter

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/api/importers.rst

Handles the ingestion and processing of Sphinx documentation packages into the hosting system.

```APIDOC
## SphinxPackageImporter

### Description
Responsible for importing Sphinx documentation packages, parsing their structure, and creating the corresponding PageTreeNode hierarchy.

### Methods
- **import_package(path)**: Processes a directory or archive containing Sphinx documentation.
- **parse_toc()**: Extracts the table of contents from the imported package.
- **build_tree()**: Constructs the PageTreeNode structure based on the parsed documentation.
```

--------------------------------

### Import Docs via API using cURL

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/importing.rst

Uploads a Sphinx documentation tarball to the django-sphinx-hosting API endpoint. Requires an API token for authentication and uses form-data with a 'file' key. The 'Content-Disposition' header is used to specify the filename.

```shell
curl \
    -XPOST \
    -H "Authorization: Token __THE_API_TOKEN__" \
    -F 'file=@path/to/yourdocs.tar.gz' \
    https://sphinx-hosting.example.com/api/v1/version/import/
```

--------------------------------

### Sphinx Configuration: Including Optional Global TOC Extension

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/packaging.rst

This snippet demonstrates how to add the optional 'sphinx_json_globaltoc' extension to your Sphinx project's configuration. This extension is beneficial for complex documentation hierarchies, as it adds a 'globaltoc' key to generated JSON files, aiding django-sphinx-hosting in building navigation.

```python
extensions = [
    'sphinx_rtd_theme',
    'sphinx_json_globaltoc'
    ...
]
```

--------------------------------

### Navigation Widgets

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/api/widgets.rst

Widgets used on every page for site navigation. Includes settings for customization.

```APIDOC
## Navigation Widgets

### Description
These widgets are used on every page to manage site navigation. Customization is possible through specific settings.

### Widgets
- SphinxHostingSidebar
- SphinxHostingMainMenu
- SphinxHostingBreadcrumbs

### Customization Settings
- ``SPHINX_HOSTING_SETTINGS['EXTRA_MENU_ITEMS']``
- ``SPHINX_HOSTING_SETTINGS['MENU_ITEM_BUILDERS']``
- ``SPHINX_HOSTING_SETTINGS['NAVBAR_CLASS']``
```

--------------------------------

### Import Docs using Django Management Command

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/overview/importing.rst

Imports a Sphinx documentation tarball into the django-sphinx-hosting database using the 'import_docs' management command. The --force option can be used to overwrite existing documentation.

```shell
./manage.py import_docs mydocs.tar.gz
```

```shell
./manage.py import_docs --force mydocs.tar.gz
```

--------------------------------

### Extend Base Template for Sphinx Hosting

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/sphinx_hosting/templates/sphinx_hosting/base.html

This snippet shows how to extend a base Django template ('academy_theme/base--wildewidgets.html') and load static files or custom Sphinx hosting tags. It includes blocks for extra CSS and footer JavaScript.

```html
{% extends 'academy_theme/base--wildewidgets.html' %} {% load static sphinx_hosting %} {% block extra_css %} {{ block.super }}  {% endblock %} {% block extra_footer_js %} {{ block.super }} fsLightbox.props.type = "image"; {% endblock %}
```

--------------------------------

### Configure Django REST Framework Settings

Source: https://github.com/caltechads/django-sphinx-hosting/blob/master/doc/source/index.rst

Configures Django REST Framework with default parsers, authentication classes, filter backends, pagination, and schema generation. It also sets the page size for API responses. These settings enable the API functionality of Django Sphinx Hosting.

```python
# djangorestframework
# ------------------------------------------------------------------------------
REST_FRAMEWORK = {
   # https://www.django-rest-framework.org/api-guide/parsers/#setting-the-parsers
   'DEFAULT_PARSER_CLASSES': ('rest_framework.parsers.JSONParser',),
   # https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication
   'DEFAULT_AUTHENTICATION_CLASSES': ('rest_framework.authentication.TokenAuthentication',),
   # https://django-filter.readthedocs.io/en/master/guide/rest_framework.html
   'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',),
   # https://www.django-rest-framework.org/api-guide/pagination/#limitoffsetpagination
   'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
   # https://github.com/tfranzel/drf-spectacular
   'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
   'PAGE_SIZE': 100,
}

# drf-spectacular

```