`readthedocs.projects`¶

`readthedocs.projects.admin`¶

Django administration interface for projects.models

class readthedocs.projects.admin.DomainAdmin(model, admin_site)¶

model¶: alias of readthedocs.projects.models.Domain

class readthedocs.projects.admin.DomainInline(parent_model, admin_site)¶

model¶: alias of readthedocs.projects.models.Domain

class readthedocs.projects.admin.FeatureAdmin(model, admin_site)¶

form¶: alias of readthedocs.projects.forms.FeatureForm

model¶: alias of readthedocs.projects.models.Feature

class readthedocs.projects.admin.ImportedFileAdmin(model, admin_site)¶: Admin view for ImportedFile

class readthedocs.projects.admin.ProjectAdmin(model, admin_site)¶

Project model admin view.

ban_owner(request, queryset)¶

Ban project owner.

This will only ban single owners, because a malicious user could add a user as a co-owner of the project. We don’t want to induce and collatoral damage when flagging users.

delete_selected_and_artifacts(request, queryset)¶

Remove HTML/etc artifacts from application instances.

Prior to the query delete, broadcast tasks to delete HTML artifacts from application instances.

get_actions(request)¶: Return a dictionary mapping the names of all actions for this ModelAdmin to a tuple of (callable, name, description) for each action.

class readthedocs.projects.admin.ProjectOwnerBannedFilter(request, params, model, model_admin)¶

Filter for projects with banned owners.

There are problems adding users__profile__banned to the list_filter attribute, so we’ll create a basic filter to capture banned owners.

lookups(request, model_admin)¶: Must be overridden to return a list of tuples (value, verbose value)

queryset(request, queryset)¶: Returns the filtered queryset.

class readthedocs.projects.admin.ProjectRelationshipInline(parent_model, admin_site)¶

Project inline relationship view for ProjectAdmin

model¶: alias of readthedocs.projects.models.ProjectRelationship

class readthedocs.projects.admin.ProjectSendNotificationView(**kwargs)¶

get_object_recipients(obj)¶

Iterate over queryset objects and return User objects.

This allows for non-User querysets to pass back a list of Users to send to. By default, assume we’re working with User objects and just yield the single object.

For example, this could be made to return project owners with:

for owner in project.users.all():
    yield owner

Parameters:	obj – object from queryset, type is dependent on model class
Return type:	django.contrib.auth.models.User

class readthedocs.projects.admin.RedirectInline(parent_model, admin_site)¶

Redirect inline relationship view for ProjectAdmin

model¶: alias of readthedocs.redirects.models.Redirect

class readthedocs.projects.admin.VersionInline(parent_model, admin_site)¶

Version inline relationship view for ProjectAdmin

model¶: alias of readthedocs.builds.models.Version

`readthedocs.projects.constants`¶

Project constants.

Default values and other various configuration for projects, including available theme names and repository types.

class readthedocs.projects.forms.BaseVersionsForm(data=None, files=None, auto_id=u'id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None)¶

Form for versions page.

save_version(version)¶: Save version if there has been a change, trigger a rebuild.

class readthedocs.projects.forms.DomainForm(*args, **kwargs)¶

Form to configure a custom domain name for a project.

class Meta¶

model¶: alias of readthedocs.projects.models.Domain

class readthedocs.projects.forms.DualCheckboxWidget(version, attrs=None, check_test=<type 'bool'>)¶: Checkbox with link to the version’s built documentation.

class readthedocs.projects.forms.EmailHookForm(*args, **kwargs)¶: Project email notification form.

class readthedocs.projects.forms.FeatureForm(*args, **kwargs)¶

Project feature form for dynamic admin choices.

This form converts the CharField into a ChoiceField on display. The underlying driver won’t attempt to do validation on the choices, and so we can dynamically populate this list.

class Meta¶

model¶: alias of readthedocs.projects.models.Feature

class readthedocs.projects.forms.IntegrationForm(*args, **kwargs)¶

Form to add an integration.

This limits the choices of the integration type to webhook integration types

class Meta¶

model¶: alias of readthedocs.integrations.models.Integration

class readthedocs.projects.forms.ProjectAdvancedForm(*args, **kwargs)¶

Advanced project option form.

class Meta¶

model¶: alias of readthedocs.projects.models.Project

class readthedocs.projects.forms.ProjectAdvertisingForm(*args, **kwargs)¶

Project promotion opt-out form.

class Meta¶

model¶: alias of readthedocs.projects.models.Project

class readthedocs.projects.forms.ProjectBackendForm(data=None, files=None, auto_id=u'id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None)¶: Get the import backend.

class readthedocs.projects.forms.ProjectBasicsForm(*args, **kwargs)¶

Form for basic project fields.

class Meta¶

model¶: alias of readthedocs.projects.models.Project

save(commit=True)¶: Add remote repository relationship to the project instance.

class readthedocs.projects.forms.ProjectExtraForm(*args, **kwargs)¶

Additional project information form.

class Meta¶

model¶: alias of readthedocs.projects.models.Project

class readthedocs.projects.forms.ProjectForm(*args, **kwargs)¶

Project form.

Parameters:	user – If provided, add this user as a project user on save

class readthedocs.projects.forms.ProjectRelationshipBaseForm(*args, **kwargs)¶

Form to add/update project relationships.

class Meta¶

model¶: alias of readthedocs.projects.models.ProjectRelationship

get_subproject_queryset()¶

Return scrubbed subproject choice queryset.

This removes projects that are either already a subproject of another project, or are a superproject, as neither case is supported.

class readthedocs.projects.forms.ProjectRelationshipForm¶

class readthedocs.projects.forms.ProjectTriggerBuildMixin¶

Mixin to trigger build on form save.

This should be replaced with signals instead of calling trigger_build explicitly.

save(commit=True)¶: Trigger build on commit save.

class readthedocs.projects.forms.RedirectForm(*args, **kwargs)¶

Form for project redirects.

class Meta¶

model¶: alias of readthedocs.redirects.models.Redirect

class readthedocs.projects.forms.TranslationBaseForm(*args, **kwargs)¶: Project translation form.

class readthedocs.projects.forms.TranslationForm¶

class readthedocs.projects.forms.UserForm(*args, **kwargs)¶: Project user association form.

class readthedocs.projects.forms.WebHookForm(*args, **kwargs)¶: Project webhook form.

readthedocs.projects.forms.build_upload_html_form(project)¶: Upload HTML form with list of versions to upload HTML for.

readthedocs.projects.forms.build_versions_form(project)¶: Versions form with a list of versions and version privacy levels.

`readthedocs.projects.models`¶

Project models.

class readthedocs.projects.models.APIProject(*args, **kwargs)¶

Project proxy model for API data deserialization.

This replaces the pattern where API data was deserialized into a mocked :py:cls:`Project` object. This pattern was confusing, as it was not explicit as to what form of object you were working with – API backed or database backed.

This model preserves the Project model methods, allowing for overrides on model field differences. This model pattern will generally only be used on builder instances, where we are interacting solely with API data.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

class readthedocs.projects.models.Domain(*args, **kwargs)¶

A custom domain name for a project.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

class readthedocs.projects.models.EmailHook(id, project, email)¶

exception DoesNotExist¶

exception MultipleObjectsReturned¶

class readthedocs.projects.models.Feature(*args, **kwargs)¶

Project feature flags.

Features should generally be added here as choices, however features may also be added dynamically from a signal in other packages. Features can be added by external packages with the use of signals:

@receiver(pre_init, sender=Feature)
def add_features(sender, **kwargs):
    sender.FEATURES += (('blah', 'BLAH'),)

The FeatureForm will grab the updated list on instantiation.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

get_feature_display()¶

Implement display name field for fake ChoiceField.

Because the field is not a ChoiceField here, we need to manually implement this behavior.

class readthedocs.projects.models.ImportedFile(*args, **kwargs)¶

Imported files model.

This tracks files that are output from documentation builds, useful for things like CDN invalidation.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

class readthedocs.projects.models.Project(*args, **kwargs)¶

Project model.

exception DoesNotExist¶

exception MultipleObjectsReturned¶

all_active_versions()¶

Get queryset with all active versions.

Note

This is a temporary workaround for activate_versions filtering out things that were active, but failed to build

Returns:	`Version` queryset

artifact_path(type_, version='latest')¶: The path to the build html docs in the project.

conf_file(version='latest')¶: Find a conf.py file in the project checkout.

find(filename, version)¶

Find files inside the project’s doc path.

Parameters:	filename – Filename to search for in project checkout version – Version instance to set version checkout path

full_build_path(version='latest')¶: The path to the build html docs in the project.

full_dash_path(version='latest')¶: The path to the build dash docs in the project.

full_doc_path(version='latest')¶: The path to the documentation root in the project.

full_epub_path(version='latest')¶: The path to the build epub docs in the project.

full_find(filename, version)¶

Find files inside a project’s checkout path.

Parameters:	filename – Filename to search for in project checkout version – Version instance to set version checkout path

full_json_path(version='latest')¶: The path to the build json docs in the project.

full_latex_path(version='latest')¶: The path to the build LaTeX docs in the project.

full_man_path(version='latest')¶: The path to the build man docs in the project.

full_singlehtml_path(version='latest')¶: The path to the build singlehtml docs in the project.

get_default_branch()¶: Get the version representing ‘latest’.

get_default_version()¶

Get the default version (slug).

Returns self.default_version if the version with that slug actually exists (is built and published). Otherwise returns ‘latest’.

get_docs_url(version_slug=None, lang_slug=None, private=None)¶

Return a URL for the docs.

Always use http for now, to avoid content warnings.

get_feature_value(feature, positive, negative)¶

Look up project feature, return corresponding value.

If a project has a feature, return positive, otherwise return negative

get_latest_build(finished=True)¶

Get latest build for project.

Parameters:	finished – Return only builds that are in a finished state

get_production_media_path(type_, version_slug, include_file=True)¶

Used to see if these files exist so we can offer them for download.

Parameters:	type – Media content type, ie - ‘pdf’, ‘zip’ version_slug – Project version slug for lookup include_file (bool) – Include file name in return
Returns:	Full path to media file or path

get_production_media_url(type_, version_slug, full_path=True)¶: Get the URL for downloading a specific media file.

get_subproject_urls()¶

List subproject URLs.

This is used in search result linking

has_feature(feature_id)¶

Does project have existing feature flag.

If the feature has a historical True value before the feature was added, we consider the project to have the flag. This is used for deprecating a feature or changing behavior for new projects

is_type_mkdocs¶: Is project type Mkdocs.

is_type_sphinx¶: Is project type Sphinx.

pip_cache_path¶: Path to pip cache.

rtd_build_path(version='latest')¶: The destination path where the built docs are copied.

static_metadata_path()¶: The path to the static metadata JSON settings file.

subdomain()¶: Get project subdomain from resolver.

supported_versions()¶

Get the list of supported versions.

Returns:	List of version strings.

translations_symlink_path(language=None)¶: Path in the doc_path that we symlink translations.

update_stable_version()¶

Returns the version that was promoted to be the new stable version.

Return None if no update was mode or if there is no version on the project that can be considered stable.

vcs_repo(version='latest', environment=None)¶

Return a Backend object for this project able to handle VCS commands.

Parameters:	environment (doc_builder.environments.BuildEnvironment) – environment to run the commands version (str) – version slug for the backend (`LATEST` by default)

class readthedocs.projects.models.ProjectRelationship(*args, **kwargs)¶

Project to project relationship.

This is used for subprojects

exception DoesNotExist¶

exception MultipleObjectsReturned¶

class readthedocs.projects.models.WebHook(id, project, url)¶

exception DoesNotExist¶

exception MultipleObjectsReturned¶

`readthedocs.projects.search_indexes`¶

`readthedocs.projects.tasks`¶

Tasks related to projects.

This includes fetching repository code, cleaning conf.py files, and rebuilding documentation.

class readthedocs.projects.tasks.SyncRepositoryMixin¶

Mixin that handles the VCS sync/update.

static get_version(project=None, version_pk=None)¶

Retrieve version data from the API.

Parameters:	project (projects.models.Project) – project object to sync version_pk (int) – version pk to sync
Returns:	a data-complete version object
Return type:	builds.models.APIVersion

sync_repo()¶: Update the project’s repository and hit sync_versions API.

class readthedocs.projects.tasks.SyncRepositoryTask¶: Celery task to trigger VCS version sync.

class readthedocs.projects.tasks.SyncRepositoryTaskStep¶

Entry point to synchronize the VCS documentation.

Note

This is implemented as a separate class to isolate each run of the underlying task. Previously, we were using a custom celery.Task for this, but this class is only instantiated once – on startup. The effect was that this instance shared state between workers.

run(version_pk)¶

Run the VCS synchronization.

Parameters:	version_pk (int) – version pk to sync
Returns:	whether or not the task ended successfully
Return type:	bool

class readthedocs.projects.tasks.UpdateDocsTaskStep(build_env=None, python_env=None, config=None, force=False, search=True, localmedia=True, build=None, project=None, version=None, task=None)¶

The main entry point for updating documentation.

It handles all of the logic around whether a project is imported, we created it or a webhook is received. Then it will sync the repository and build the html docs if needed.

Note

This is implemented as a separate class to isolate each run of the underlying task. Previously, we were using a custom celery.Task for this, but this class is only instantiated once – on startup. The effect was that this instance shared state between workers.

build_docs()¶

Wrapper to all build functions.

Executes the necessary builds for this task and returns whether the build was successful or not.

Returns:	Build outcomes with keys for html, search, localmedia, pdf, and epub
Return type:	dict

build_docs_class(builder_class)¶

Build docs with additional doc backends.

These steps are not necessarily required for the build to halt, so we only raise a warning exception here. A hard error will halt the build process.

build_docs_epub()¶: Build ePub docs.

build_docs_html()¶: Build HTML docs.

build_docs_localmedia()¶: Get local media files with separate build.

build_docs_pdf()¶: Build PDF docs.

build_docs_search()¶: Build search data with separate build.

static get_build(build_pk)¶

Retrieve build object from API.

Parameters:	build_pk – Build primary key

get_env_vars()¶: Get bash environment variables used for all builder commands.

static get_project(project_pk)¶: Get project from API.

run(pk, version_pk=None, build_pk=None, record=True, docker=None, search=True, force=False, localmedia=True, **__)¶

Run a documentation sync n’ build.

This is fully wrapped in exception handling to account for a number of failure cases. We first run a few commands in a local build environment, but do not report on environment success. This avoids a flicker on the build output page where the build is marked as finished in between the local environment steps and the docker build steps.

If a failure is raised, or the build is not successful, return False, otherwise, True.

Unhandled exceptions raise a generic user facing error, which directs the user to bug us. It is therefore a benefit to have as few unhandled errors as possible.

Parameters:	int (build_pk) – Project id int – Project Version id (latest if None) int – Build id (if None, commands are not recorded) bool (localmedia) – record a build object in the database bool – use docker to build the project (if `None`, `settings.DOCKER_ENABLE` is used) bool – update search bool – force Sphinx build bool – update localmedia
Returns:	whether build was successful or not
Return type:	bool

run_build(docker, record)¶

Build the docs in an environment.

Parameters:	docker – if `True`, the build uses a `DockerBuildEnvironment`, otherwise it uses a `LocalBuildEnvironment` to run all the commands to build the docs record – whether or not record all the commands in the `Build` instance

run_setup(record=True)¶

Run setup in the local environment.

Return True if successful.

send_notifications()¶: Send notifications on build failure.

set_valid_clone()¶: Mark on the project that it has been cloned properly.

setup_python_environment()¶

Build the virtualenv and install the project into it.

Always build projects with a virtualenv.

Parameters:	build_env – Build environment to pass commands and execution through.

setup_vcs()¶

Update the checkout of the repo to make sure it’s the latest.

This also syncs versions in the DB.

Parameters:	build_env – Build environment

update_app_instances(html=False, localmedia=False, search=False, pdf=False, epub=False)¶

Update application instances with build artifacts.

This triggers updates across application instances for html, pdf, epub, downloads, and search. Tasks are broadcast to all web servers from here.

update_documentation_type()¶

Force Sphinx for ‘auto’ documentation type.

This used to determine the type and automatically set the documentation type to Sphinx for rST and Mkdocs for markdown. It now just forces Sphinx, due to markdown support.

readthedocs.projects.tasks.email_notification(version, build, email)¶

Send email notifications for build failure.

Parameters:	version – `Version` instance that failed build – `Build` instance that failed email – Email recipient address

readthedocs.projects.tasks.webhook_notification(version, build, hook_url)¶

Send webhook notification for project webhook.

Parameters:	version – Version instance to send hook for build – Build instance that failed hook_url – Hook URL to send to

`readthedocs.projects.utils`¶

Utility functions used by projects.

class readthedocs.projects.utils.DictObj¶

readthedocs.projects.utils.find_file(filename)¶

Recursively find matching file from the current working path.

Parameters:	file – Filename to match
Returns:	A list of matching filenames.

readthedocs.projects.utils.run(*commands)¶

Run one or more commands.

Each argument in commands can be passed as a string or as a list. Passing as a list is the preferred method, as space escaping is more explicit and it avoids the need for executing anything in a shell.

If more than one command is given, then this is equivalent to chaining them together with &&; if all commands succeed, then (status, out, err) will represent the last successful command. If one command failed, then (status, out, err) will represent the failed command.

Returns:	`(status, out, err)`

readthedocs.projects.utils.safe_write(filename, contents)¶

Normalize and write to filename.

Write contents to the given filename. If the filename’s directory does not exist, it is created. Contents are written as UTF-8, ignoring any characters that cannot be encoded as UTF-8.

Parameters:	filename – Filename to write to contents – File contents to write to file

`readthedocs.projects.views`¶

`readthedocs.projects.views.public`¶

Public project views.

class readthedocs.projects.views.public.ProjectDetailView(**kwargs)¶

Display project onboard steps.

model¶: alias of readthedocs.projects.models.Project

class readthedocs.projects.views.public.ProjectIndex(**kwargs)¶

List view of public Project instances.

model¶: alias of readthedocs.projects.models.Project

readthedocs.projects.views.public.elastic_project_search(request, project_slug)¶: Use elastic search to search in a project.

readthedocs.projects.views.public.file_autocomplete(request, project_slug)¶: Return a json list of file names.

readthedocs.projects.views.public.project_analytics(request, project_slug)¶: Have a analytics API placeholder.

readthedocs.projects.views.public.project_badge(request, *args, **kwargs)¶: Return a sweet badge for the project.

readthedocs.projects.views.public.project_download_media(request, project_slug, type_, version_slug)¶

Download a specific piece of media.

Perform an auth check if serving in private mode.

Warning

This is linked directly from the HTML pages. It should only care about the Version permissions, not the actual Project permissions.

readthedocs.projects.views.public.project_downloads(request, project_slug)¶: A detail view for a project with various dataz.

readthedocs.projects.views.public.project_embed(request, project_slug)¶: Have a content API placeholder.

readthedocs.projects.views.public.project_index(request, *args, **kwargs)¶: List view of public Project instances.

readthedocs.projects.views.public.project_versions(request, project_slug)¶

Project version list view.

Shows the available versions and lets the user choose which ones to build.

readthedocs.projects.views.public.search_autocomplete(request)¶: Return a json list of project names.

readthedocs.projects.views.public.version_autocomplete(request, project_slug)¶: Return a json list of version names.

`readthedocs.projects.views.private`¶

Project views for authenticated users.

class readthedocs.projects.views.private.AliasList(**kwargs)¶

model¶: alias of readthedocs.builds.models.VersionAlias

class readthedocs.projects.views.private.ImportDemoView(**kwargs)¶

View to pass request on to import form to import demo project.

form_class¶: alias of readthedocs.projects.forms.ProjectBasicsForm

get(request, *args, **kwargs)¶: Process link request as a form post to the project import form.

get_form_data()¶: Get form data to post to import form.

get_form_kwargs()¶: Form kwargs passed in during instantiation.

class readthedocs.projects.views.private.ImportView(**kwargs)¶

On GET, show the source an import view, on POST, mock out a wizard.

If we are accepting POST data, use the fields to seed the initial data in ImportWizardView. The import templates will redirect the form to /dashboard/import

get(request, *args, **kwargs)¶

Display list of repositories to import.

Adds a warning to the listing if any of the accounts connected for the user are not supported accounts.

wizard_class¶: alias of ImportWizardView

class readthedocs.projects.views.private.ImportWizardView(**kwargs)¶

Project import wizard.

done(form_list, **kwargs)¶

Save form data as object instance.

Don’t save form data directly, instead bypass documentation building and other side effects for now, by signalling a save without commit. Then, finish by added the members to the project and saving.

get_form_kwargs(step=None)¶: Get args to pass into form instantiation.

get_template_names()¶: Return template names based on step name.

is_advanced()¶: Determine if the user selected the show advanced field.

class readthedocs.projects.views.private.IntegrationMixin¶

Project external service mixin for listing webhook objects.

form_class¶: alias of readthedocs.projects.forms.IntegrationForm

get_integration()¶: Return project integration determined by url kwarg.

model¶: alias of readthedocs.integrations.models.Integration

class readthedocs.projects.views.private.IntegrationWebhookSync(**kwargs)¶

Resync a project webhook.

The signal will add a success/failure message on the request.

class readthedocs.projects.views.private.PrivateViewMixin¶

class readthedocs.projects.views.private.ProjectAdvertisingUpdate(**kwargs)¶

form_class¶: alias of readthedocs.projects.forms.ProjectAdvertisingForm

get_queryset()¶

Returns the base queryset for the view.

Either used as a list of objects to display, or as the queryset from which to perform the individual object lookup.

model¶: alias of readthedocs.projects.models.Project

class readthedocs.projects.views.private.ProjectDashboard(**kwargs)¶

Project dashboard.

model¶: alias of readthedocs.projects.models.Project

readthedocs.projects.views.private.edit_alias(request, *args, **kwargs)¶: Edit project alias form view.

readthedocs.projects.views.private.project_delete(request, *args, **kwargs)¶

Project delete confirmation view.

Make a project as deleted on POST, otherwise show a form asking for confirmation of delete.

readthedocs.projects.views.private.project_manage(request, *args, **kwargs)¶

Project management view.

Where you will have links to edit the projects’ configuration, edit the files associated with that project, etc.

Now redirects to the normal /projects/<slug> view.

readthedocs.projects.views.private.project_notifications(request, *args, **kwargs)¶: Project notification view and form view.

readthedocs.projects.views.private.project_notifications_delete(request, *args, **kwargs)¶: Project notifications delete confirmation view.

readthedocs.projects.views.private.project_redirects(request, *args, **kwargs)¶: Project redirects view and form view.

readthedocs.projects.views.private.project_redirects_delete(request, *args, **kwargs)¶: Project redirect delete view.

readthedocs.projects.views.private.project_translations(request, *args, **kwargs)¶: Project translations view and form view.

readthedocs.projects.views.private.project_users(request, *args, **kwargs)¶: Project users view and form view.

readthedocs.projects.views.private.project_version_delete_html(request, *args, **kwargs)¶

Project version ‘delete’ HTML.

This marks a version as not built

readthedocs.projects.views.private.project_version_detail(request, *args, **kwargs)¶: Project version detail page.

readthedocs.projects.views.private.project_versions(request, *args, **kwargs)¶

Project versions view.

Shows the available versions and lets the user choose which ones he would like to have built.

readthedocs.projects¶

readthedocs.projects.search_indexes¶

readthedocs.projects.views¶

`readthedocs.projects`¶

`readthedocs.projects.search_indexes`¶

`readthedocs.projects.views`¶