`readthedocs.projects`¶

`readthedocs.projects.admin`¶

Django administration interface for projects.models

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

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

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

Project inline relationship view for ProjectAdmin

model¶: alias of ProjectRelationship

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

Redirect inline relationship view for ProjectAdmin

model¶: alias of Redirect

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

Version inline relationship view for ProjectAdmin

model¶: alias of 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 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.IntegrationForm(*args, **kwargs)¶

Form to add an integration

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

class readthedocs.projects.forms.ProjectAdvancedForm(*args, **kwargs)¶: Advanced project option form

class readthedocs.projects.forms.ProjectAdvertisingForm(*args, **kwargs)¶: Project promotion opt-out form

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

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

class readthedocs.projects.forms.ProjectExtraForm(*args, **kwargs)¶: Additional project information form

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.ProjectRelationshipForm(*args, **kwargs)¶

Form to add/update project relationships

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.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 readthedocs.projects.forms.TranslationForm(*args, **kwargs)¶: Project translation form

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.Domain(*args, **kwargs)¶: A custom domain name for a project.

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

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.

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

Project model

add_comment(version_slug, page, content_hash, commit, user, text)¶

Add comment to node

Parameters:	version_slug – Version slug to use for node lookup page – Page to attach comment to content_hash – Hash of content to apply comment to commit – Commit that updated comment user – `User` instance that created comment text – Comment text

add_node(content_hash, page, version, commit)¶

Add comment node

Parameters:	content_hash – Hash of node content page – Doc page for node version (str) – Slug for project version to apply node to commit (str) – Commit that node was updated in

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_latest_build(finished=True)¶

Get latest build for project

finished: Return only builds that are in a finished state

get_production_media_path(type_, version_slug, include_file=True)¶

This is 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

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.

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

Project to project relationship

This is used for subprojects

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

`readthedocs.projects.search_indexes`¶

Project search indexes

Deprecated since version Read: the Docs no longer uses Haystack in production and the core team does not maintain this code. Use at your own risk, this may go away soon.

class readthedocs.projects.search_indexes.ImportedFileIndex¶

Search index for imported files

index_queryset(using=None)¶: Used when the entire index for model is updated

prepare_text(obj)¶

Prepare the text of the html file

This only works on machines that have the html files for the projects checked out.

class readthedocs.projects.search_indexes.ProjectIndex¶

Project search index

index_queryset(using=None)¶: Used when the entire index for model is updated

`readthedocs.projects.tasks`¶

Tasks related to projects

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

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

The main entry point for updating documentation.

It handles all of the logic around whether a project is imported or we created it. Then it will build the html docs and other requested parts.

pk: Primary key of the project to update
record: Whether or not to keep a record of the update in the database. Useful for preventing changes visible to the end-user when running commands from the shell, for example.

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

static get_version(project, version_pk)¶: Ensure we’re using a sane version

run_build(docker=False, record=True)¶

Build the docs in an environment.

If docker is True, or Docker is enabled by the settings.DOCKER_ENABLE setting, then build in a Docker environment. Otherwise build locally.

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_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_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

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.make_api_project(project_data)¶: Make mock Project instance from API return

readthedocs.projects.utils.make_api_version(version_data)¶: Make mock Version instance from API return

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 Project

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

List view of public Project instances

model¶: alias of 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.ImportDemoView(**kwargs)¶

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

form_class¶: alias of 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 IntegrationForm

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

model¶: alias of 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.ProjectDashboard(**kwargs)¶

Project dashboard

model¶: alias of 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.views¶

`readthedocs.projects`¶

`readthedocs.projects.views`¶