0
# Edit Page Integration
1
2
Functionality for generating "edit this page" links that work with GitHub, GitLab, and Bitbucket repositories, supporting custom URL templates and multiple version control platforms.
3
4
## Capabilities
5
6
### Edit URL Generation
7
8
Generates edit URLs for version control platforms and injects them into template context.
9
10
```python { .api }
11
def setup_edit_url(
12
app: Sphinx, pagename: str, templatename: str, context, doctree
13
) -> None:
14
"""
15
Add a function that jinja can access for returning the edit URL of a page.
16
17
This function adds a 'get_edit_provider_and_url' function to the template
18
context that generates edit URLs for GitHub, GitLab, Bitbucket, or custom
19
providers based on the configuration.
20
21
Parameters:
22
- app (Sphinx): Sphinx application instance
23
- pagename (str): Name of the current page being processed
24
- templatename (str): Template being used
25
- context: Template context dictionary
26
- doctree: Document tree for the current page
27
28
The function also sets theme_show_toc_level as an integer in the context.
29
"""
30
```
31
32
## Configuration
33
34
### GitHub Integration
35
36
```python
37
# conf.py
38
html_context = {
39
"github_user": "username",
40
"github_repo": "repository",
41
"github_version": "main", # branch/tag name
42
"doc_path": "docs/", # path to docs in repo
43
}
44
45
html_theme_options = {
46
"use_edit_page_button": True
47
}
48
```
49
50
### GitLab Integration
51
52
```python
53
# conf.py
54
html_context = {
55
"gitlab_user": "username",
56
"gitlab_repo": "repository",
57
"gitlab_version": "main",
58
"doc_path": "docs/",
59
}
60
61
html_theme_options = {
62
"use_edit_page_button": True
63
}
64
```
65
66
### Bitbucket Integration
67
68
```python
69
# conf.py
70
html_context = {
71
"bitbucket_user": "username",
72
"bitbucket_repo": "repository",
73
"bitbucket_version": "main",
74
"doc_path": "docs/",
75
}
76
77
html_theme_options = {
78
"use_edit_page_button": True
79
}
80
```
81
82
### Custom URL Template
83
84
```python
85
# conf.py - Custom edit URL pattern
86
html_context = {
87
"edit_page_url_template": "https://myforge.com/{{ user }}/{{ repo }}/edit/{{ version }}/{{ file_name }}",
88
"edit_page_provider_name": "MyForge",
89
"user": "username",
90
"repo": "repository",
91
"version": "main",
92
"doc_path": "documentation/",
93
}
94
95
html_theme_options = {
96
"use_edit_page_button": True
97
}
98
```
99
100
## URL Templates
101
102
The edit URLs are generated using the following templates:
103
104
### GitHub
105
```
106
{{ github_url }}/{{ github_user }}/{{ github_repo }}/edit/{{ github_version }}/{{ doc_path }}{{ file_name }}
107
```
108
109
### GitLab
110
```
111
{{ gitlab_url }}/{{ gitlab_user }}/{{ gitlab_repo }}/-/edit/{{ gitlab_version }}/{{ doc_path }}{{ file_name }}
112
```
113
114
### Bitbucket
115
```
116
{{ bitbucket_url }}/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version }}/{{ doc_path }}{{ file_name }}?mode=edit
117
```
118
119
## Default Provider URLs
120
121
- **GitHub**: `https://github.com`
122
- **GitLab**: `https://gitlab.com`
123
- **Bitbucket**: `https://bitbucket.org`
124
125
These can be overridden by setting the corresponding `*_url` context variables.
126
127
## Usage Examples
128
129
### Basic GitHub Setup
130
131
```python
132
# conf.py
133
html_context = {
134
"github_user": "pydata",
135
"github_repo": "pydata-sphinx-theme",
136
"github_version": "main",
137
"doc_path": "docs/",
138
}
139
140
html_theme_options = {
141
"use_edit_page_button": True,
142
"icon_links": [
143
{
144
"name": "GitHub",
145
"url": "https://github.com/pydata/pydata-sphinx-theme",
146
"icon": "fa-brands fa-github"
147
}
148
]
149
}
150
```
151
152
### Enterprise GitHub
153
154
```python
155
# conf.py
156
html_context = {
157
"github_url": "https://github.enterprise.com",
158
"github_user": "orgname",
159
"github_repo": "project",
160
"github_version": "develop",
161
"doc_path": "documentation/source/",
162
}
163
```
164
165
### Self-hosted GitLab
166
167
```python
168
# conf.py
169
html_context = {
170
"gitlab_url": "https://gitlab.mycompany.com",
171
"gitlab_user": "team",
172
"gitlab_repo": "product-docs",
173
"gitlab_version": "master",
174
"doc_path": "docs/",
175
}
176
```
177
178
### Complex Custom Template
179
180
```python
181
# conf.py - Advanced custom template with multiple variables
182
html_context = {
183
"edit_page_url_template": "https://forge.example.com/{{ org }}/{{ project }}/{{ repo }}/edit/{{ branch }}/{{ doc_path }}{{ file_name }}?view=edit",
184
"edit_page_provider_name": "Example Forge",
185
"org": "engineering",
186
"project": "documentation",
187
"repo": "user-guide",
188
"branch": "latest",
189
"doc_path": "source/",
190
}
191
```
192
193
## Template Context
194
195
The edit page functionality injects a `get_edit_provider_and_url` function into the template context that returns:
196
197
- **Provider name**: Human-readable name (e.g., "GitHub", "GitLab")
198
- **Edit URL**: Complete URL for editing the current page
199
200
## Error Handling
201
202
The function raises `ExtensionError` in these cases:
203
204
- Required configuration values are missing
205
- Custom URL template doesn't contain `{{ file_name }}`
206
- No valid provider configuration is found
207
208
## TOC Level Configuration
209
210
The function also sets `theme_show_toc_level` as an integer in the context, controlling the depth of the table of contents display.
211
212
## Required Variables
213
214
For each provider, you must provide:
215
216
**GitHub**: `github_user`, `github_repo`, `github_version`
217
**GitLab**: `gitlab_user`, `gitlab_repo`, `gitlab_version`
218
**Bitbucket**: `bitbucket_user`, `bitbucket_repo`, `bitbucket_version`
219
**Custom**: `edit_page_url_template` (must contain `{{ file_name }}`)
220
221
Optional variables:
222
- `doc_path`: Path to documentation within repository (defaults to empty)
223
- Provider-specific base URLs (`github_url`, `gitlab_url`, `bitbucket_url`)