0
# Sphinx Issues
1

2
A Sphinx extension for linking to your project's issue tracker. Includes roles for linking to issues, pull requests, user profiles, commits, and PyPI packages, with built-in support for GitHub (though this works with other services like GitLab).
3

4
## Package Information
5

6
- **Package Name**: sphinx-issues
7
- **Package Type**: pip
8
- **Language**: Python
9
- **Installation**: `pip install sphinx-issues`
10

11
## Core Imports
12

13
```python
14
import sphinx_issues
15
```
16

17
Extension registration in `conf.py`:
18

19
```python
20
extensions = [
21
    # ...
22
    "sphinx_issues"
23
]
24
```
25

26
## Basic Usage
27

28
```python
29
# docs/conf.py
30

31
# ...
32
extensions = [
33
    # ...
34
    "sphinx_issues"
35
]
36

37
# Path to GitHub repo {group}/{project}  (note that `group` is the GitHub user or organization)
38
issues_github_path = "sloria/marshmallow"
39
```
40

41
Then in reStructuredText documents:
42

43
```rst
44
See issue :issue:`42`
45

46
See issues :issue:`12,13`
47

48
See :issue:`sloria/konch#45`.
49

50
See PR :pr:`58`
51

52
Thanks to :user:`bitprophet` for the idea!
53

54
Fixed in :commit:`6bb9124d5e9dbb2f7b52864c3d8af7feb1b69403`.
55

56
:pypi:`sphinx-issues` - A Sphinx extension for linking to your project's issue tracker.
57
```
58

59
## Capabilities
60

61
### Issue Role
62

63
Links to issue tracker issues with configurable URI templates and prefixes.
64

65
```python { .api }
66
issue_role = IssueRole(config_prefix="issues")
67
"""
68
Sphinx role for linking to an issue. Must have
69
`issues_uri` or `issues_default_group_project` configured in conf.py.
70

71
Usage: :issue:`123` or :issue:`sloria/konch#123`
72

73
Parameters when called:
74
- name: Role name
75
- rawtext: Raw text content
76
- text: Issue reference (e.g., "123", "42,45", "sloria/konch#123")
77
- lineno: Line number in source
78
- inliner: Sphinx inliner object
79
- options: Optional rendering options
80
- content: Optional content list
81

82
Returns:
83
tuple: (list of nodes, list of messages)
84
"""
85
```
86

87
Usage patterns:
88
- Single issue: `:issue:`123``
89
- Multiple issues: `:issue:`42,45``
90
- External repository: `:issue:`sloria/konch#123``
91
- Custom title: `:issue:`Fix critical bug <123>``
92

93
### Pull Request Role
94

95
Links to pull requests with configurable URI templates and prefixes.
96

97
```python { .api }
98
pr_role = IssueRole(config_prefix="issues_pr")
99
"""
100
Sphinx role for linking to a pull request. Must have
101
`issues_pr_uri` or `issues_default_group_project` configured in conf.py.
102

103
Usage: :pr:`123` or :pr:`sloria/konch#43`
104

105
Parameters when called:
106
- name: Role name
107
- rawtext: Raw text content  
108
- text: PR reference (e.g., "123", "42,45", "sloria/konch#43")
109
- lineno: Line number in source
110
- inliner: Sphinx inliner object
111
- options: Optional rendering options
112
- content: Optional content list
113

114
Returns:
115
tuple: (list of nodes, list of messages)
116
"""
117
```
118

119
Usage patterns:
120
- Single PR: `:pr:`123``
121
- Multiple PRs: `:pr:`42,45``
122
- External repository: `:pr:`sloria/konch#43``
123
- Custom title: `:pr:`Great feature <123>``
124

125
### Commit Role
126

127
Links to repository commits with shortened SHA display.
128

129
```python { .api }
130
commit_role = IssueRole(config_prefix="issues_commit", pre_format_text=format_commit_text)
131
"""
132
Sphinx role for linking to a commit. Must have
133
`issues_commit_uri` or `issues_default_group_project` configured in conf.py.
134

135
Usage: :commit:`123abc456def` or :commit:`sloria/konch@123abc456def`
136

137
Parameters when called:
138
- name: Role name
139
- rawtext: Raw text content
140
- text: Commit reference (e.g., "123abc456def", "sloria/konch@123abc456def")
141
- lineno: Line number in source
142
- inliner: Sphinx inliner object
143
- options: Optional rendering options
144
- content: Optional content list
145

146
Returns:
147
tuple: (list of nodes, list of messages)
148
"""
149
```
150

151
Usage patterns:
152
- Commit SHA: `:commit:`123abc456def`` (displays as @123abc4)
153
- External repository: `:commit:`sloria/webargs@abc123def456``
154
- Custom title: `:commit:`1.0.0 (2016-07-05) <170ce9>``
155

156
### User Role
157

158
Links to user profiles with configurable URI templates.
159

160
```python { .api }
161
user_role = IssueRole(config_prefix="issues_user")
162
"""
163
Sphinx role for linking to a user profile. Defaults to linking to
164
GitHub profiles, but the profile URIs can be configured via the
165
issues_user_uri config value.
166

167
Usage: :user:`sloria` or :user:`Steven Loria <sloria>`
168

169
Parameters when called:
170
- name: Role name
171
- rawtext: Raw text content
172
- text: User reference (e.g., "sloria", "Steven Loria <sloria>")
173
- lineno: Line number in source
174
- inliner: Sphinx inliner object
175
- options: Optional rendering options
176
- content: Optional content list
177

178
Returns:
179
tuple: (list of nodes, list of messages)
180
"""
181
```
182

183
Usage patterns:
184
- Username: `:user:`sloria`` (displays as @sloria)
185
- Custom title: `:user:`Steven Loria <sloria>``
186

187
### PyPI Role
188

189
Links to PyPI package pages.
190

191
```python { .api }
192
def pypi_role(name, rawtext, text, lineno, inliner, options=None, content=None):
193
    """
194
    Sphinx role for linking to a PyPI package page.
195
    
196
    Parameters:
197
    - name: Role name
198
    - rawtext: Raw text content
199
    - text: Package name (e.g., "sphinx-issues")
200
    - lineno: Line number in source
201
    - inliner: Sphinx inliner object
202
    - options: Optional rendering options
203
    - content: Optional content list
204
    
205
    Returns:
206
    tuple: (list of nodes, list of messages)
207
    """
208
```
209

210
Usage patterns:
211
- Package name: `:pypi:`sphinx-issues``
212
- Custom title: `:pypi:`Great Extension <sphinx-issues>``
213

214
### Extension Setup
215

216
Main extension setup function that registers all roles and configuration options.
217

218
```python { .api }
219
def setup(app):
220
    """
221
    Sphinx extension setup function. Registers all roles and configuration options.
222
    
223
    Parameters:
224
    - app: Sphinx application instance
225
    
226
    Returns:
227
    dict: Extension metadata with version, parallel_read_safe, and parallel_write_safe flags
228
    """
229
```
230

231
Automatically registers:
232
- All role functions (:issue:, :pr:, :commit:, :user:, :pypi:)
233
- All configuration options with defaults
234
- Extension metadata
235

236
## Configuration Options
237

238
### URI Templates
239

240
Control where links point to for different services:
241

242
```python { .api }
243
# Issue tracker URI template
244
issues_uri = "https://github.com/{group}/{project}/issues/{issue}"
245

246
# Pull request URI template  
247
issues_pr_uri = "https://github.com/{group}/{project}/pull/{pr}"
248

249
# Commit URI template
250
issues_commit_uri = "https://github.com/{group}/{project}/commit/{commit}"
251

252
# User profile URI template (defaults to GitHub sponsors)
253
issues_user_uri = "https://github.com/sponsors/{user}"
254
```
255

256
### Display Prefixes
257

258
Control the prefix symbols shown in rendered links:
259

260
```python { .api }
261
# Issue number prefix (default: "#")
262
issues_prefix = "#"
263

264
# PR number prefix (default: "#")  
265
issues_pr_prefix = "#"
266

267
# Commit prefix (default: "@")
268
issues_commit_prefix = "@"
269

270
# User prefix (default: "@")
271
issues_user_prefix = "@"
272
```
273

274
### Repository Settings
275

276
Define default repository for relative references:
277

278
```python { .api }
279
# GitHub repository path (legacy, group/project format)
280
issues_github_path = "sloria/marshmallow"
281

282
# Universal repository path (replaces issues_github_path)
283
issues_default_group_project = "sloria/marshmallow"
284
```
285

286
Note: Only one of `issues_github_path` or `issues_default_group_project` should be set.
287

288
### GitLab Configuration Example
289

290
```python
291
# docs/conf.py
292
extensions = ["sphinx_issues"]
293

294
# Default repo {group}/{project} of gitlab project
295
issues_default_group_project = "myteam/super_great_project"
296
issues_uri = "https://gitlab.company.com/{group}/{project}/-/issues/{issue}"
297
issues_prefix = "#"
298
issues_pr_uri = "https://gitlab.company.com/{group}/{project}/-/merge_requests/{pr}"
299
issues_pr_prefix = "!"
300
issues_commit_uri = "https://gitlab.company.com/{group}/{project}/-/commit/{commit}"
301
issues_commit_prefix = "@"
302
issues_user_uri = "https://gitlab.company.com/{user}"
303
issues_user_prefix = "@"
304
```
305

306
## Advanced Features
307

308
### External Repository References
309

310
All roles support external repository references using the format `group/project{separator}reference`:
311

312
- Issues: `sloria/konch#123`
313
- Pull requests: `sloria/konch#43`
314
- Commits: `sloria/konch@abc123def456`
315

316
### Multiple References
317

318
Issue and PR roles support comma-separated lists:
319

320
```rst
321
See issues :issue:`12,13,14`
322
See PRs :pr:`42,45,58`
323
```
324

325
### Custom Titles
326

327
All roles support custom anchor text:
328

329
```rst
330
:issue:`Fix critical bug <123>`
331
:pr:`Great feature <456>`
332
:commit:`1.0.0 Release <abc123>`
333
:user:`Steven Loria <sloria>`
334
:pypi:`Great Extension <sphinx-issues>`
335
```
336

337
## Types
338

339
```python { .api }
340
def format_commit_text(config, sha):
341
    """
342
    Formats commit SHA to first 7 characters.
343
    
344
    Parameters:
345
    - config: Sphinx configuration object
346
    - sha: Full commit SHA string
347
    
348
    Returns:
349
    str: Truncated SHA (first 7 characters)
350
    """
351

352
class IssueRole:
353
    """
354
    Base class for creating issue tracker roles.
355
    
356
    Attributes:
357
    - ELEMENT_SEPARATORS (str): Valid separators "#@!"
358
    - EXTERNAL_REPO_REGEX (Pattern): Regex for external repository references
359
    """
360
    
361
    def __init__(self, config_prefix: str, pre_format_text: Callable[[Config, str], str] = None):
362
        """
363
        Initialize IssueRole instance.
364
        
365
        Parameters:
366
        - config_prefix: Configuration prefix for URI and separator settings
367
        - pre_format_text: Optional text formatting function
368
        """
369
    
370
    def __call__(self, name, rawtext, text, lineno, inliner, options=None, content=None):
371
        """
372
        Main role implementation method.
373
        
374
        Parameters:
375
        - name: Role name
376
        - rawtext: Raw text content
377
        - text: Reference text
378
        - lineno: Line number in source
379
        - inliner: Sphinx inliner object
380
        - options: Optional rendering options
381
        - content: Optional content list
382
        
383
        Returns:
384
        tuple: (list of nodes, list of messages)
385
        """
386
    
387
    def make_node(self, name: str, issue_no: str, config: Config, options=None):
388
        """
389
        Creates docutils reference nodes.
390
        
391
        Parameters:
392
        - name: Role name
393
        - issue_no: Issue/PR/commit reference
394
        - config: Sphinx configuration object
395
        - options: Optional rendering options
396
        
397
        Returns:
398
        docutils.nodes.reference or None
399
        """
400
    
401
    def format_text(self, config: Config, issue_no: str) -> str:
402
        """
403
        Add supported separator in front of the issue or raise an error if invalid
404
        separator is given.
405
        
406
        Parameters:
407
        - config: Sphinx configuration object
408
        - issue_no: Issue number to format
409
        
410
        Returns:
411
        str: Formatted text with prefix
412
        """
413
```
414

415
## Error Handling
416

417
The extension validates configuration and raises helpful errors for:
418

419
- Missing required configuration (URI templates or default repository)
420
- Invalid separators (must be one of "#", "@", "!")
421
- Malformed repository paths (must be "group/project" format)
422
- Invalid URI template placeholders (only {group}, {project}, and role-specific placeholders allowed)
423
- Conflicting configuration options (both legacy and new repository settings)