Importers

class sphinx_hosting.importers.PageTreeNode(page: SphinxPage, parent_title: str | None = None, next_title: str | None = None)

A data structure to temporarily hold relationships between sphinx_hosting.models.SphinxPage objects while importing pages.

In the page JSON we get from Sphinx, we only know the titles of related pages, so we store them here along with the sphinx_hosting.models.SphinxPage we created from our JSON, and then do another pass through these PageTreeNode objects to link our pages together.

This is used in SphinxPackageImporter.link_pages.

__init__(page: SphinxPage, parent_title: str | None = None, next_title: str | None = None) → None

next_title: str | None = None

page: SphinxPage

parent_title: str | None = None

class sphinx_hosting.importers.SphinxPackageImporter

Usage: SphinxPackageImporter().run(sphinx_tarfilename)`

Import a tarfile of a built set of Sphinx documentation into the database.

Important

Before importing, there must be a sphinx_hosting.models.Project in the database whose machine_name matches the project in Sphinx’s conf.py config file for the docs to be imported.

The documentation package should have been built via the json output from sphinx-build, so either:

make json

or:

sphinx-build -n -b json build/json

The tarfile should be built like so:

cd build
tar zcf mydocs.tar.gz json

ensuring that the package contents are enclosed in a folder.

When run, SphinxPackageImporter will look inside the tarfile at the globalcontext.json file to determine which project and version we should associate these pages with.

• The project key in will be used to look up the sphinx_hosting.models.Project to associate these Sphinx pages with, using project as sphinx_hosting.models.Project.machine_name

• The version key will be used to create a new sphinx_hosting.models.Version object tied to that project

Once the sphinx_hosting.models.Version has been created, the pages in the tarfile will be created as sphinx_hosting.models.SphinxPage objects, and the images will be created as sphinx_hosting.models.SphinxImage objects.

__init__() → None

get_version(force: bool = False) → Version

Look in package for a member named globalcontext.json, and load that file as JSON.

Extract these things from that JSON:

• the version string from the release key.

• the machine_name of the Project for this documentation tarfile as the slugified version of the project key

Return a new Version instance on the project.

Keyword Arguments:

force – if True, re-use an existing version, purging any docs and images associated with it first

Raises:

• Project.DoesNotExist – no Project exists whose machine_name matches the slugified project setting in the Sphinx package’s conf.py

• VersionAlreadyExists – a Version with version string release from the Sphinx conf.py already exists for our project, and force was not True

import_documents(package: TarFile, version: Version) → None

Import all downloadable documents in our Sphinx documentation into the database (and our Django storage) before importing any pages.

Parameters:

• package – the opened Sphinx documentation tarfile

• version – the Version which which to associate our documents

import_images(package: TarFile, version: Version) → None

Import all images in our Sphinx documentation into the database before importing any pages, then return a lookup dict for doing <img src="image_path"> replacements in the page bodies.

Parameters:

• package – the opened Sphinx documentation tarfile

• version – the Version which which to associate our images

import_pages(package: TarFile, version: Version) → None

Import a all pages from package into the database as sphinx_hosting.models.SphinxPage objects, associating them with Version version.

Parameters:

• package – the tarfile of the sphinx docs

• version – the Version object to associated data

Returns:

The page linkage tree for consumption by link_pages.

link_pages() → None

Given page_tree`, a list of page linkages (parent, next, prev), link all the sphinx_hosting.models.SphinxPage objects in that list to their next page and their parent page.

Parameters:

tree – the page linkage tree

load_config(package: TarFile) → None

Load the globalcontext.json file for later reference.

Parameters:

package – the opened Sphinx documentation tarfile

run(filename: str | None = None, file_obj: IO | None = None, force: bool = False) → Version

Load the pages in the tarfile identified by filename into the database as Version version of Project project. See the class docs for SphinxPackageImporter for more background on how to prepare the package named by filename.

Keyword Arguments:

• filename – the filename of the gzipped tar archive of the Sphinx pages

• file_obj – an open file object of the gzipped tar archive of the Sphinx pages

• force – if True, overwrite the docs for an existing version

Raises:

• Project.DoesNotExist – no Project exists whose machine_name matches the slugified project setting in the Sphinx package’s conf.py

• VersionAlreadyExists – a Version with version string release from the Sphinx package’s conf.py already exists for our project, and force was not True

config: dict[str, Any]

document_map: dict[str, sphinx_hosting.models.SphinxDocument]

image_map: dict[str, sphinx_hosting.models.SphinxImage]

page_tree: dict[str, sphinx_hosting.importers.PageTreeNode]