Logo

First steps

  • Read the Docs tutorial
  • Getting Started with Sphinx
  • Getting Started with MkDocs
  • Importing Your Documentation
  • Choosing Between Our Two Platforms

Features

  • Main Features
  • Configuration File
  • VCS Integrations
  • Custom Domains
  • Versioned Documentation
  • Downloadable Documentation
  • Documentation Hosting Features
  • Server Side Search
  • Traffic Analytics
  • Preview Documentation from Pull Requests
  • Build Notifications and Webhooks
  • Security log and auditing
  • Connecting Your VCS Account
  • Build process
  • Build customization
  • Build troubleshooting
  • Environment Variables
  • Status Badges
  • Site Support
  • Frequently Asked Questions

How-to Guides

  • Guides for documentation authors
  • Guides for project administrators
  • Guides for developers and designers
    • Installing Private Python Packages
    • Using Private Git Submodules
    • Adding Custom CSS or JavaScript to Sphinx Documentation
    • Reproducible Builds
    • Embedding Content From Your Documentation
    • Conda Support
    • Removing “Edit on …” Buttons from Documentation
    • My Build is Using Too Many Resources
    • Adding “Edit Source” links on your Sphinx theme
      • GitHub
      • Bitbucket
      • Gitlab
      • Additional variables
    • Setup Build Notifications
  • Read the Docs for Science
  • Example projects

Advanced features

  • Subprojects
  • Single Version Documentation
  • Flyout Menu
  • Feature Flags
  • Localization of Documentation
  • User-defined Redirects
  • Automatic Redirects
  • Automation Rules
  • Canonical URLs
  • Public API

Read the Docs for Business

  • Read the Docs for Business
  • Organizations
  • Project Privacy Level
  • Sharing
  • Single Sign-On
  • How to manage your Read the Docs for Business subscription

About Read the Docs

  • Security
  • DMCA Takedown Policy
  • Policy for Abandoned Projects
  • Policy for Unofficial and Unmaintained Projects
  • Changelog
  • About Read the Docs
  • Read the Docs Team
  • Read the Docs Open Source Philosophy
  • The Story of Read the Docs
  • Advertising
  • Sponsors of Read the Docs
  • Legal Documents and Policies
  • Developer Documentation
  • Glossary
  • Google Summer of Code
Read the Docs user documentation
  • Guides for developers and designers
  • Adding “Edit Source” links on your Sphinx theme
  • Edit on GitHub

Adding “Edit Source” links on your Sphinx theme¶

Read the Docs injects some extra variables in the Sphinx html_context that are used by our Sphinx theme to display “edit source” links at the top of all pages. You can use these variables in your own Sphinx theme as well.

More information can be found on Sphinx documentation.

GitHub¶

If you want to integrate GitHub, these are the required variables to put into your conf.py:

html_context = {
    "display_github": True, # Integrate GitHub
    "github_user": "MyUserName", # Username
    "github_repo": "MyDoc", # Repo name
    "github_version": "master", # Version
    "conf_py_path": "/source/", # Path in the checkout to the docs root
}

They can be used like this:

{% if display_github %}
    <li><a href="https://github.com/{{ github_user }}/{{ github_repo }}
    /blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}.rst">
    Show on GitHub</a></li>
{% endif %}

Bitbucket¶

If you want to integrate Bitbucket, these are the required variables to put into your conf.py:

html_context = {
    "display_bitbucket": True, # Integrate Bitbucket
    "bitbucket_user": "MyUserName", # Username
    "bitbucket_repo": "MyDoc", # Repo name
    "bitbucket_version": "master", # Version
    "conf_py_path": "/source/", # Path in the checkout to the docs root
}

They can be used like this:

{% if display_bitbucket %}
    <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}
    /src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'"
    class="icon icon-bitbucket"> Edit on Bitbucket</a>
{% endif %}

Gitlab¶

If you want to integrate Gitlab, these are the required variables to put into your conf.py:

html_context = {
    "display_gitlab": True, # Integrate Gitlab
    "gitlab_user": "MyUserName", # Username
    "gitlab_repo": "MyDoc", # Repo name
    "gitlab_version": "master", # Version
    "conf_py_path": "/source/", # Path in the checkout to the docs root
}

They can be used like this:

{% if display_gitlab %}
    <a href="https://{{ gitlab_host|default("gitlab.com") }}/
    {{ gitlab_user }}/{{ gitlab_repo }}/blob/{{ gitlab_version }}
    {{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab">
    Edit on GitLab</a>
{% endif %}

Additional variables¶

  • 'pagename' - Sphinx variable representing the name of the page you’re on.

Previous Next

© Copyright Read the Docs, Inc & contributors. Revision 5ab0da07.

Built with Sphinx using a theme provided by Read the Docs.
Read the Docs v: stable
Versions
latest
stable
diataxis-main
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds