Models

Fields

class sphinx_hosting.fields.MachineNameField(*args, max_length=50, db_index=True, allow_unicode=False, **kwargs)[source]

This is just a django.forms.SlugField that also allows “.” characters. “.” is not uncommon in some project names, especially if the project is named after the website domain it hosts.

formfield(**kwargs)[source]: Return a django.forms.Field instance for this field.

Managers

class sphinx_hosting.models.ClassifierManager(*args, **kwargs)[source]

tree() → Dict[str, ClassifierNode][source]

Given our classifiers, which are :: separated lists of terms like:

Section :: Subsection :: Name
Section :: Subsection :: Name2
Section :: Subsection :: Name3
Section :: Subsection

Return a tree-like data structure that looks like:

{
    'Section': ClassifierNode(
        title='Section'
        items={
            'Subsection': ClassifierNode(
                title='Subsection',
                classifier=Classifier(name="Section :: Subsection"),
                items: {
                    'Name': ClassifierNode(
                        title='Name',
                        classifier=Classifier(
                            name='Section :: Subsection :: Name'
                        )
                    ),
                    ...
                }
            )
        }
    )
}

Models

class sphinx_hosting.models.Classifier(*args, **kwargs)[source]

Database table: sphinxhostingcore_classifier

A Project can be tagged with one or more Classifier tags. This allows you to group projects by ecosystem, or type, for example.

Use PyPI classifiers as an example of how to use a single field for classifying across many dimensions.

Examples:

Ecosystem :: CMS
Language :: Python
Owner :: DevOps :: AWS

Parameters

id (AutoField) – Primary key: ID
name (CharField) – Classifier Name. The classifier spec for this classifier, e.g. “Language :: Python”

Reverse relationships:

Parameters: projects (Reverse ManyToManyField from Project) – All projects of this classifier (related name of classifiers)

exception DoesNotExist

exception MultipleObjectsReturned

save(*args, **kwargs) → None[source]

Overrides django.db.models.Model.save.

Override save to create any missing classifiers in our chain. For example, if we want to create this classifier:

Foo :: Bar :: Baz

But Foo :: Bar does not yet exist in the database, create that before creating Foo :: Bar :: Baz. We do this so that when we filter our projects by classifier, we can filter by Foo :: Bar and Foo :: Bar :: Baz.

id

Type: AutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

name: Field

Type: CharField

Classifier Name. The classifier spec for this classifier, e.g. “Language :: Python”

A wrapper for a deferred-loading field. When the value is read from this

objects = <sphinx_hosting.models.ClassifierManager object>

projects

Type: Reverse ManyToManyField from Project

All projects of this classifier (related name of classifiers)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

class sphinx_hosting.models.Project(*args, **kwargs)[source]

Database table: sphinxhostingcore_project

A Project is what a set of Sphinx docs describes: an application, a library, etc.

Projects have versions (Version) and versions have Sphinx pages (SphinxPage).

Parameters

id (AutoField) – Primary key: ID
created (CreationDateTimeField) – Created
modified (ModificationDateTimeField) – Modified
title (CharField) –
Project Name. The human name for this project

The page title
description (CharField) – Brief Description. A brief description of this project
machine_name (MachineNameField) – Machine Name. Must be unique. Set this to the slugified value of “project” in Sphinx’s. conf.py

Relationship fields:

Parameters

permission_groups (ManyToManyField to ProjectPermissionGroup) – Permission groups (related name: projects)
classifiers (ManyToManyField to Classifier) – Classifiers (related name: projects)

Reverse relationships:

Parameters

versions (Reverse ForeignKey from Version) – All versions of this project (related name of project)
related_links (Reverse ForeignKey from ProjectRelatedLink) – All related links of this project (related name of project)

exception DoesNotExist

exception MultipleObjectsReturned

get_absolute_url() → str[source]

Return the standard URL for viewing/editing this instance of this model.

Returns: The update URL for this instance.

get_latest_version_url() → Optional[str][source]

get_next_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=True, **kwargs): Finds next instance based on created. See get_next_by_FOO for more information.

get_next_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=True, **kwargs): Finds next instance based on modified. See get_next_by_FOO for more information.

get_previous_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=False, **kwargs): Finds previous instance based on created. See get_previous_by_FOO for more information.

get_previous_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=False, **kwargs): Finds previous instance based on modified. See get_previous_by_FOO for more information.

get_update_url() → str[source]

Return a URL suitable for POSTing to to update this instance of this model.

Returns: The update URL for this instance.

classifiers: ManyToManyField

Type: ManyToManyField to Classifier

Classifiers (related name: projects)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

created

Type: CreationDateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

description: Field

Type: CharField

Brief Description. A brief description of this project

A wrapper for a deferred-loading field. When the value is read from this

id

Type: AutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

property latest_version: Optional[Version]

Return the latest version (by version number) of our project documentation, if any.

Returns: The latest version of our project.

machine_name: Field

Type: MachineNameField

Machine Name. Must be unique. Set this to the slugified value of “project” in Sphinx’s. conf.py

A wrapper for a deferred-loading field. When the value is read from this

modified

Type: ModificationDateTimeField

Modified

A wrapper for a deferred-loading field. When the value is read from this

objects = <django.db.models.Manager object>

permission_groups: ManyToManyField

Type: ManyToManyField to ProjectPermissionGroup

Permission groups (related name: projects)

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

Pizza.toppings and Topping.pizzas are ManyToManyDescriptor instances.

Most of the implementation is delegated to a dynamically defined manager

related_links

Type: Reverse ForeignKey from ProjectRelatedLink

All related links of this project (related name of project)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

title: Field

Type: CharField

Project Name. The human name for this project

A wrapper for a deferred-loading field. When the value is read from this

versions

Type: Reverse ForeignKey from Version

All versions of this project (related name of project)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

class sphinx_hosting.models.ProjectRelatedLink(*args, **kwargs)[source]

Database table: sphinxhostingcore_projectrelatedlink

A ProjectRelatedLink is a link to an external resource that is related to a Project.

Parameters

id (AutoField) – Primary key: ID
created (CreationDateTimeField) – Created
modified (ModificationDateTimeField) – Modified
title (CharField) –
Link Title. The title for this link

The page title
uri (URLField) – Link URL. The URL for this link

Relationship fields:

Parameters: project (ForeignKey to Project) – Project. The project to which this link is related (related name: related_links)

exception DoesNotExist

exception MultipleObjectsReturned

get_delete_url() → str[source]

get_next_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=True, **kwargs): Finds next instance based on created. See get_next_by_FOO for more information.

get_next_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=True, **kwargs): Finds next instance based on modified. See get_next_by_FOO for more information.

get_previous_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=False, **kwargs): Finds previous instance based on created. See get_previous_by_FOO for more information.

get_previous_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=False, **kwargs): Finds previous instance based on modified. See get_previous_by_FOO for more information.

get_update_url() → str[source]

created

Type: CreationDateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

id

Type: AutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

modified

Type: ModificationDateTimeField

Modified

A wrapper for a deferred-loading field. When the value is read from this

objects = <django.db.models.Manager object>

project: ForeignKey

Type: ForeignKey to Project

Project. The project to which this link is related (related name: related_links)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

project_id: Internal field, use project instead.

title: Field

Type: CharField

Link Title. The title for this link

A wrapper for a deferred-loading field. When the value is read from this

uri: Field

Type: URLField

Link URL. The URL for this link

A wrapper for a deferred-loading field. When the value is read from this

class sphinx_hosting.models.Version(*args, **kwargs)[source]

Database table: sphinxhostingcore_version

A Version is a specific version of a Project. Versions own SphinxPage objects.

Parameters

id (AutoField) – Primary key: ID
created (CreationDateTimeField) – Created
modified (ModificationDateTimeField) – Modified
version (CharField) –
Version. The version number for this release of the Project

The :py:class:`Version that this tree examines
sphinx_version (CharField) – Sphinx Version. The version of Sphinx used to create this documentation set
archived (BooleanField) – Archived?. Whether this version should be excluded from search indexes

Relationship fields:

Parameters

project (ForeignKey to Project) – Project. The Project to which this Version belongs (related name: versions)
head (OneToOneField to SphinxPage) –
Head. The top page of the documentation set for this version of our project (related name: +)

The top page in the page hierarchy

Reverse relationships:

Parameters

pages (Reverse ForeignKey from SphinxPage) – All pages of this version (related name of version)
images (Reverse ForeignKey from SphinxImage) – All images of this version (related name of version)

exception DoesNotExist

exception MultipleObjectsReturned

get_absolute_url() → str[source]

get_next_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=True, **kwargs): Finds next instance based on created. See get_next_by_FOO for more information.

get_next_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=True, **kwargs): Finds next instance based on modified. See get_next_by_FOO for more information.

get_previous_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=False, **kwargs): Finds previous instance based on created. See get_previous_by_FOO for more information.

get_previous_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=False, **kwargs): Finds previous instance based on modified. See get_previous_by_FOO for more information.

mark_searchable_pages() → None[source]

Set the SphinxPage.searchable flag on the searchable pages in this version.

Searchable pages are ones that:

Are not in SphinxPage.SPECIAL_PAGES
Do not have a part of their relative path that starts with _.

Go through the pages in this version, and set SphinxPage.searchable to True for all those which meet the above requirements, False otherwise.

purge_cached_globaltoc() → None[source]: Purge the cached output from our globaltoc property.

save(*args, **kwargs)[source]: Overriding django.db.models.Model.save here so that we can purge our cached global table of contents.

archived: Field

Type: BooleanField

Archived?. Whether this version should be excluded from search indexes

A wrapper for a deferred-loading field. When the value is read from this

created

Type: CreationDateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

globaltoc

Build a struct that looks like this:

{
    items: [
        {'text': 'foo'},
        {'text': 'bar', 'url': '/foo', 'icon': None}
        {'text': 'bar', 'url': '/foo', 'icon': None, items: [{'text': 'blah' ...} ...]}
        ...
    ]
}

suitable for constructing a sphinx_hosting.wildewidgets.SphinxPageGlobalTableOfContentsMenu

head: ForeignKey

Type: OneToOneField to SphinxPage

Head. The top page of the documentation set for this version of our project (related name: +)

Accessor to the related object on the forward side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

head_id: Internal field, use head instead.

id

Type: AutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

images

Type: Reverse ForeignKey from SphinxImage

All images of this version (related name of version)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

property is_latest: bool

modified

Type: ModificationDateTimeField

Modified

A wrapper for a deferred-loading field. When the value is read from this

objects = <django.db.models.Manager object>

property page_tree: SphinxPageTree

Return the page hierarchy for the set of SphinxPage pages in this version.

The page hierarchy is build by traversing the pages in the set, starting with head.

Returns: The page hierarchy for this version.

pages

Type: Reverse ForeignKey from SphinxPage

All pages of this version (related name of version)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

project: ForeignKey

Type: ForeignKey to Project

Project. The Project to which this Version belongs (related name: versions)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

project_id: Internal field, use project instead.

sphinx_version: Field

Type: CharField

Sphinx Version. The version of Sphinx used to create this documentation set

A wrapper for a deferred-loading field. When the value is read from this

version: Field

Type: CharField

Version. The version number for this release of the Project

A wrapper for a deferred-loading field. When the value is read from this

class sphinx_hosting.models.SphinxPage(*args, **kwargs)[source]

Database table: sphinxhostingcore_sphinxpage

A SphinxPage is a single page of a set of Sphinx documentation. SphinxPage objects are owned Version objects, which are in turn owned by Project objects.

Parameters

id (AutoField) – Primary key: ID
created (CreationDateTimeField) – Created
modified (ModificationDateTimeField) – Modified
relative_path (CharField) – Relative page path. The path to the page under our top slug
content (TextField) – Content. The full JSON payload for the page
title (CharField) –
Title. Just the title for the page, extracted from the page JSON

The page title
orig_body (TextField) – Body (Original). The original body for the page, extracted from the page JSON. Some pages have no body. We save this here in case we need to reprocess the body at some later date.
body (TextField) – Body. The body for the page, extracted from the page JSON, and modified to suit us. Some pages have no body. The body is actually stored as a Django template.
orig_local_toc (TextField) – Local Table of Contents (original). The original table of contents for headings in this page.We save this here in case we need to reprocess the table of contents at some later date.
local_toc (TextField) – Local Table of Contents. Table of Contents for headings in this page, modified to work in our templates
orig_global_toc (TextField) – Global Table of Contents (original). The original global table of contents HTML attached to this page, if any. This will only be present if you had “sphinxcontrib-jsonglobaltoc” installed in your “extensions” in the Sphinx conf.py
searchable (BooleanField) – Searchable. Should this page be included in the search index?

Relationship fields:

Parameters

version (ForeignKey to Version) –
Version. The Version to which this page belongs (related name: pages)

The :py:class:`Version that this tree examines
parent (ForeignKey to SphinxPage) –
Parent. The parent page of this page (related name: children)

The SphinxPage that is this page’s parent
next_page (ForeignKey to SphinxPage) – Next page. The next page in the documentation set (related name: previous_page)

Reverse relationships:

Parameters

children (Reverse ForeignKey from SphinxPage) –
All children of this sphinx page (related name of parent)

The TreeNode objects that are this page’s children
previous_page (Reverse ForeignKey from SphinxPage) – All previous page of this sphinx page (related name of next_page)

exception DoesNotExist

exception MultipleObjectsReturned

get_absolute_url() → str[source]

get_next_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=True, **kwargs): Finds next instance based on created. See get_next_by_FOO for more information.

get_next_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=True, **kwargs): Finds next instance based on modified. See get_next_by_FOO for more information.

get_previous_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=False, **kwargs): Finds previous instance based on created. See get_previous_by_FOO for more information.

get_previous_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=False, **kwargs): Finds previous instance based on modified. See get_previous_by_FOO for more information.

SPECIAL_PAGES: Dict[str, str] = {'_modules/index': 'Module code', 'genindex': 'General Index', 'np-modindex': 'Module Index', 'py-modindex': 'Module Index', 'search': 'Search'}: This is a mapping between filename and title that identifies the special pages that Sphinx produces on its own and gives them reasonable titles. These pages have no title key in their

body: Field

Type: TextField

Body. The body for the page, extracted from the page JSON, and modified to suit us. Some pages have no body. The body is actually stored as a Django template.

A wrapper for a deferred-loading field. When the value is read from this

children

Type: Reverse ForeignKey from SphinxPage

All children of this sphinx page (related name of parent)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

content: Field

Type: TextField

Content. The full JSON payload for the page

A wrapper for a deferred-loading field. When the value is read from this

created

Type: CreationDateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

id

Type: AutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

local_toc: Field

Type: TextField

Local Table of Contents. Table of Contents for headings in this page, modified to work in our templates

A wrapper for a deferred-loading field. When the value is read from this

modified

Type: ModificationDateTimeField

Modified

A wrapper for a deferred-loading field. When the value is read from this

next_page: ForeignKey

Type: ForeignKey to SphinxPage

Next page. The next page in the documentation set (related name: previous_page)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

next_page_id: Internal field, use next_page instead.

objects = <django.db.models.Manager object>

orig_body: Field

Type: TextField

Body (Original). The original body for the page, extracted from the page JSON. Some pages have no body. We save this here in case we need to reprocess the body at some later date.

A wrapper for a deferred-loading field. When the value is read from this

orig_global_toc: Field

Type: TextField

Global Table of Contents (original). The original global table of contents HTML attached to this page, if any. This will only be present if you had “sphinxcontrib-jsonglobaltoc” installed in your “extensions” in the Sphinx conf.py

A wrapper for a deferred-loading field. When the value is read from this

orig_local_toc: Field

Type: TextField

Local Table of Contents (original). The original table of contents for headings in this page.We save this here in case we need to reprocess the table of contents at some later date.

A wrapper for a deferred-loading field. When the value is read from this

parent: ForeignKey

Type: ForeignKey to SphinxPage

Parent. The parent page of this page (related name: children)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

parent_id: Internal field, use parent instead.

previous_page

Type: Reverse ForeignKey from SphinxPage

All previous page of this sphinx page (related name of next_page)

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

Parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager

relative_path: Field

Type: CharField

Relative page path. The path to the page under our top slug

A wrapper for a deferred-loading field. When the value is read from this

searchable: Field

Type: BooleanField

Searchable. Should this page be included in the search index?

A wrapper for a deferred-loading field. When the value is read from this

title: Field

Type: CharField

Title. Just the title for the page, extracted from the page JSON

A wrapper for a deferred-loading field. When the value is read from this

version: ForeignKey

Type: ForeignKey to Version

Version. The Version to which this page belongs (related name: pages)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

version_id: Internal field, use version instead.

class sphinx_hosting.models.SphinxImage(*args, **kwargs)[source]

Database table: sphinxhostingcore_sphinximage

A SphinxImage is an image file referenced in a Sphinx document. When importing documenation packages, we extract all images from the package, upload them into Django storage and update the Sphinx HTML in SphinxPage.body to reference the URL for the uploaded image instead of its original url.

Parameters

id (AutoField) – Primary key: ID
created (CreationDateTimeField) – Created
modified (ModificationDateTimeField) – Modified
orig_path (CharField) – Original Path. The original path to this file in the Sphinx documentation package
file (FileField) – An image file. The actual image file

Relationship fields:

Parameters

version (ForeignKey to Version) –

Version. The version of our project documentation with which this image is associated (related name: images)

The :py:class:`Version that this tree examines

exception DoesNotExist

exception MultipleObjectsReturned

get_next_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=True, **kwargs): Finds next instance based on created. See get_next_by_FOO for more information.

get_next_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=True, **kwargs): Finds next instance based on modified. See get_next_by_FOO for more information.

get_previous_by_created(*, field=<django_extensions.db.fields.CreationDateTimeField: created>, is_next=False, **kwargs): Finds previous instance based on created. See get_previous_by_FOO for more information.

get_previous_by_modified(*, field=<django_extensions.db.fields.ModificationDateTimeField: modified>, is_next=False, **kwargs): Finds previous instance based on modified. See get_previous_by_FOO for more information.

created

Type: CreationDateTimeField

Created

A wrapper for a deferred-loading field. When the value is read from this

file: Field

Type: FileField

An image file. The actual image file

The descriptor for the file attribute on the model instance. Return a FieldFile when accessed so you can write code like:

>>> from myapp.models import MyModel
>>> instance = MyModel.objects.get(pk=1)
>>> instance.file.size

Assign a file object on assignment so you can do:

>>> with open('/path/to/hello.world') as f:

id

Type: AutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

modified

Type: ModificationDateTimeField

Modified

A wrapper for a deferred-loading field. When the value is read from this

objects = <django.db.models.Manager object>

orig_path: Field

Type: CharField

Original Path. The original path to this file in the Sphinx documentation package

A wrapper for a deferred-loading field. When the value is read from this

version: ForeignKey

Type: ForeignKey to Version

Version. The version of our project documentation with which this image is associated (related name: images)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

version_id: Internal field, use version instead.

Utility functions

sphinx_hosting.models.sphinx_image_upload_to(instance: SphinxImage, filename: str) → str[source]

Set the upload path within our MEDIA_ROOT for any images used by our Sphinx documentation to be:

{project machine_name}/{version}/images/{image basename}

Parameters

instance – the SphinxImage object
filename – the original path to the file

Returns

The properly formatted path to the file

Utility classes used by models

class sphinx_hosting.models.SphinxPageTree(version: Version)[source]

A class that holds the page hierarchy for the set of SphinxPage pages in a Version.as a linked set of TreeNode objects.

The page heirarchy is built by starting at Version.head and following the page linkages by looking at SphinxPage.next_page, stopping the traversal when we find a SphinxPage.next_page that is None.

As we traverse, if a SphinxPage.parent is not None, find the TreeNode for that parent, and add the page to TreeNode.children.

For pages who have no SpinxPage.parent, assume they are top level children of the set, and make them children of Version.head.

Load it like so:

>>> project = Project.objects.get(machine_name='my-project')
>>> version = project.versions.get(version='1.0.0')
>>> tree = SphinxPageTree(version)

You can then traverse the built hierarchy by starting at SphinxPageTree.head, looking at its children, then looking at their children, etc..

>>>

__init__(version: Version)[source]

traverse() → List[SphinxPage][source]: Return a list of the pages represented in this tree.

head: TreeNode

version: Version

class:`Version that this tree examines

Type: The

class sphinx_hosting.models.SphinxPageTreeProcessor[source]

build(items: List[Dict[str, Any]], node: TreeNode) → None[source]

Build a wildewdigets.MenuItem compatible dict representing node, and append it to items.

if node has children, recurse into those children, building out our submenus.

Parameters

items – the current list of MenuItem compatible dicts for the current level of the menu
node – the current node in our page tree

build_item(node: TreeNode) → Dict[str, Any][source]

Build a wildewdigets.MenuItem compatible dict representing node.

Parameters: node – the current node in our page tree
Returns: A dict suitable for loading into a wildewidgets.MenuItem.

run(version: Version) → List[Dict[str, Any]][source]

Parse the Version.page_tree and return a struct that works with sphinx_hosting.wildewidgets.SphinxPageGlobalTableOfContentsMenu.parse_obj

The returned struct should look something like this:

[
    {'text': 'foo'},
    {'text': 'bar', 'url': '/foo', 'icon': None}
    {'text': 'bar', 'url': '/foo', 'icon': None, items: [{'text': 'blah' ...} ...]}
    ...
]

Parameters: version – the version whose global table of contents we are parsing
Returns: A list of dicts representing the global menu structure

class sphinx_hosting.models.SphinxGlobalTOCHTMLProcessor(max_level: int = 2)[source]

Usage: SphinxGlobalTOCHTMLProcessor().run(version, globaltoc_html)`

This importer is used to parse the globaltoc key in JSON output of Sphinx pages built with the sphinxcontrib-jsonglobaltoc extension.

Sphinx uses your .. toctree: declarations in your .rst files to build site navigation for your document tree, and sphinxcontrib-jsonglobaltoc saves the Sphinx HTML produced by those ..toctree as the globaltoc key in the .fjson output.

Note

Sphinx .. toctree: are ad-hoc – they’re up to how the author wants to organize their content, and may not reflect how files are filled out in the filesystem.

__init__(max_level: int = 2) → None[source]

parse_globaltoc(html: HtmlElement) → List[Dict[str, Any]][source]

Parse our global table of contents HTML blob and return a list of sphinx_hosting.wildewidgets.MenuItem objects.

Add a first node that points to the root doc, also. The root doc can’t add itself to its toctree blocks, so we need to do it ourselves.

How our mapping works:

Multiple top level <ul> tags separated by  tags will be merged into a single list.
CONTENTS becomes {'text': 'CONTENTS'}`
Any href will be converted to its full django-sphinx-hosting path

Parameters

version – the version whose global table of contents we are parsing
html – the lxml parsed HTML of the global table of contents from Sphinx

parse_ul(html: HtmlElement, level: int = 1) → List[Dict[str, Any]][source]

Process html, an lxml parsed set of elements representing the contents of a <ul> from a Sphinx table of contents and return a list of sphinx_hosting.wildewidgets.MenuItem objects.

Any href in links found will be converted to its full django-sphinx-hosting path.

If we find another <ul> inside html, process it by passing its contents to parse_ul again, incrementing the menu level.

If level is greater than max_level, return an empty list, stopping our recursion.

Parameters: html – the list of elements that are the contents of the parent <ul>
Keyword Arguments: level – the current menu level
Returns: The <ul> contents as a list of dicts

run(version: Version, verbose: bool = False) → List[Dict[str, Any]][source]

Parse the global table of contents found as version.head.orig_global_toc into a data struct suitable for use with sphinx_hosting.wildewidgets.SphinxPageGlobalTableOfContentsMenu.parse_obj and return it.

How our mapping works:

Multiple top level <ul> tags separated by  tags will be merged into a single list.
CONTENTS becomes {'text': 'CONTENTS'}`
Any href for links found will be converted to its full django-sphinx-hosting path

The returned struct should look something like this:

[
    {'text': 'foo'},
    {'text': 'bar', 'url': '/project/version/foo', 'icon': None}
    {'text': 'bar', 'url': '/project/version/bar', 'icon': None, items: [{'text': 'blah' ...} ...]}
    ...
]

Parameters: version – the version whose global table of contents we are parsing
Keyword Arguments: verbose – if True, pretty print the HTML of the globaltoc
Returns: A list of dicts representing the global menu structure

max_level: int

class sphinx_hosting.models.TreeNode(title: str, page: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, prev: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, next: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, parent: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, children: ~typing.List[~sphinx_hosting.models.TreeNode] = <factory>)[source]

This is a dataclass that we use with SphinxPageTree to build out the global navigation structure for a set of documentation for a Version.

__init__(title: str, page: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, prev: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, next: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, parent: ~typing.Optional[~sphinx_hosting.models.SphinxPage] = None, children: ~typing.List[~sphinx_hosting.models.TreeNode] = <factory>) → None

classmethod from_page(page: SphinxPage) → TreeNode[source]

Build a TreeNode from page.

Note

This does not populate children; SphinxPageTree will populate it as appropriate as it ingests pages.

Parameters: page – the SphinxPage from which to build a node
Returns: A configured node.

children: List[TreeNode]

next: Optional[SphinxPage] = None

page: Optional[SphinxPage] = None

parent: Optional[SphinxPage] = None

prev: Optional[SphinxPage] = None

title: str

class sphinx_hosting.models.ClassifierNode(title: str, classifier: Union[ForwardRef('Classifier'), NoneType] = None, items: Dict[str, ForwardRef('ClassifierNode')] = <factory>)[source]

__init__(title: str, classifier: ~typing.Optional[~sphinx_hosting.models.Classifier] = None, items: ~typing.Dict[str, ~sphinx_hosting.models.ClassifierNode] = <factory>) → None