Importers
- class sphinx_hosting.importers.PageTreeNode(page: SphinxPage, parent_title: Optional[str] = None, next_title: Optional[str] = None)[source]
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 thesePageTreeNode
objects to link our pages together.This is used in
SphinxPackageImporter.link_pages
.- __init__(page: SphinxPage, parent_title: Optional[str] = None, next_title: Optional[str] = None) None
- page: SphinxPage
- class sphinx_hosting.importers.SphinxPackageImporter[source]
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 whosemachine_name
matches theproject
in Sphinx’sconf.py
config file for the docs to be imported.The documentation package should have been built via the
json
output fromsphinx-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 theglobalcontext.json
file to determine which project and version we should associate these pages with.The
project
key in will be used to look up thesphinx_hosting.models.Project
to associate these Sphinx pages with, usingproject
assphinx_hosting.models.Project.machine_name
The
version
key will be used to create a newsphinx_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 assphinx_hosting.models.SphinxPage
objects, and the images will be created assphinx_hosting.models.SphinxImage
objects.- get_version(package: TarFile, force: bool = False) Version [source]
Look in
package
for a member namedglobalcontext.json
, and load that file as JSON.Extract these things from that JSON:
the version string from the
release
key.the
machine_name
of theProject
for this documentation tarfile as the slugified version of theproject
key
Return a new
Version
instance on the project.- Parameters
package – the opened Sphinx documentation tarfile
- 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 whosemachine_name
matches the slugifiedproject
setting in the Sphinx package’sconf.py
VersionAlreadyExists – a
Version
with version stringrelease
from the Sphinxconf.py
already exists for our project, andforce
was notTrue
- import_images(package: TarFile, version: Version) None [source]
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 [source]
Import a all pages from
package
into the database assphinx_hosting.models.SphinxPage
objects, associating them withVersion
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 [source]
Given
page_tree`
, a list of page linkages (parent, next, prev), link all thesphinx_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 [source]
Load the
globalcontext.json
file for later reference.- Parameters
package – the opened Sphinx documentation tarfile
- run(filename: Optional[str] = None, file_obj: Optional[IO] = None, force: bool = False) Version [source]
Load the pages in the tarfile identified by
filename
into the database asVersion
version
ofProject
project
. See the class docs forSphinxPackageImporter
for more background on how to prepare the package named byfilename
.- Parameters
filename – the filename of the gzipped tar archive of the Sphinx pages
- Keyword Arguments
force – if
True
, overwrite the docs for an existing version- Raises
Project.DoesNotExist – no
Project
exists whosemachine_name
matches the slugifiedproject
setting in the Sphinx package’sconf.py
VersionAlreadyExists – a
Version
with version stringrelease
from the Sphinx package’sconf.py
already exists for our project, andforce
was notTrue
- image_map: Dict[str, SphinxImage]
- page_tree: Dict[str, PageTreeNode]