0
# GitHub Integration
1

2
Comprehensive GitHub integration providing custom Sphinx domain, roles for issues/PRs/users/repositories, and API-powered features. This integration enables seamless linking to GitHub resources with automatic title fetching and proper formatting.
3

4
## Capabilities
5

6
### GitHub Domain
7

8
Custom Sphinx domain that provides specialized roles and directives for GitHub integration.
9

10
```python { .api }
11
class GitHubDomain(Domain):
12
    """Sphinx domain for GitHub.com integration."""
13
    
14
    name = 'github'
15
    label = 'GitHub'
16
    
17
    roles = {
18
        'issue': IssueRole(),
19
        'pull': PullRole(), 
20
        'user': UserRole(),
21
        'org': UserRole(),
22
        'repo': RepoRole(),
23
    }
24
    
25
    def clear_doc(self, docname: str) -> None: ...
26
    def merge_info(self, docnames: List[str], other: Domain) -> None: ...
27

28
def validate_config(app: Sphinx, config: ToolboxConfig) -> None:
29
    """
30
    Validate GitHub configuration values.
31
    
32
    Args:
33
        app: Sphinx application instance
34
        config: Configuration object to validate
35
        
36
    Raises:
37
        MissingOptionError: When github_username or github_repository missing
38
    """
39
```
40

41
### Issue and Pull Request Integration
42

43
Link to GitHub issues and pull requests with automatic title fetching from the GitHub API.
44

45
```python { .api }
46
class IssueNode(Element):
47
    """Node for GitHub issue/PR links."""
48

49
class IssueNodeWithName(Element):  
50
    """Issue node that includes repository name."""
51

52
def issue_role(
53
    name: str,
54
    rawtext: str, 
55
    text: str,
56
    lineno: int,
57
    inliner: Inliner,
58
    options: Dict[str, Any] = {},
59
    content: List[str] = []
60
) -> Tuple[List[Node], List[system_message]]:
61
    """
62
    Role for linking to GitHub issues.
63
    
64
    Args:
65
        name: Role name ('issue')
66
        rawtext: Raw role text
67
        text: Issue number or 'user/repo#number'
68
        lineno: Line number in document
69
        inliner: Sphinx inliner
70
        options: Role options
71
        content: Role content
72
        
73
    Returns:
74
        Tuple of issue nodes and any error messages
75
    """
76

77
def pull_role(
78
    name: str,
79
    rawtext: str,
80
    text: str, 
81
    lineno: int,
82
    inliner: Inliner,
83
    options: Dict[str, Any] = {},
84
    content: List[str] = []
85
) -> Tuple[List[Node], List[system_message]]:
86
    """
87
    Role for linking to GitHub pull requests.
88
    
89
    Similar signature to issue_role but for pull requests.
90
    """
91

92
def get_issue_title(username: str, repository: str, issue_number: int) -> str:
93
    """
94
    Fetch issue/PR title from GitHub API.
95
    
96
    Args:
97
        username: GitHub username or organization
98
        repository: Repository name
99
        issue_number: Issue or pull request number
100
        
101
    Returns:
102
        Issue/PR title from GitHub API
103
        
104
    Raises:
105
        requests.RequestException: If API request fails
106
    """
107
```
108

109
Usage:
110

111
```rst
112
:github:issue:`123` 
113
:github:issue:`user/repo#456`
114
:github:pull:`789`
115
:issue:`123`  (when github_username/github_repository configured)
116
:pull:`456`   (when github_username/github_repository configured)
117
```
118

119
### Repository and User Links
120

121
Create links to GitHub repositories, users, and organizations.
122

123
```python { .api }
124
class GitHubObjectLinkNode(Element):
125
    """Node for GitHub repository/user links."""
126

127
def repository_role(
128
    name: str,
129
    rawtext: str,
130
    text: str,
131
    lineno: int, 
132
    inliner: Inliner,
133
    options: Dict[str, Any] = {},
134
    content: List[str] = []
135
) -> Tuple[List[Node], List[system_message]]:
136
    """
137
    Role for linking to GitHub repositories.
138
    
139
    Args:
140
        name: Role name ('repo')
141
        rawtext: Raw role text
142
        text: Repository in format 'user/repo'
143
        lineno: Line number in document
144
        inliner: Sphinx inliner
145
        options: Role options
146
        content: Role content
147
        
148
    Returns:
149
        Tuple of repository link nodes and any error messages
150
    """
151

152
def user_role(
153
    name: str,
154
    rawtext: str, 
155
    text: str,
156
    lineno: int,
157
    inliner: Inliner,
158
    options: Dict[str, Any] = {},
159
    content: List[str] = []
160
) -> Tuple[List[Node], List[system_message]]:
161
    """
162
    Role for linking to GitHub users/organizations.
163
    
164
    Args:
165
        name: Role name ('user' or 'org')
166
        rawtext: Raw role text
167
        text: Username or organization name
168
        lineno: Line number in document
169
        inliner: Sphinx inliner
170
        options: Role options
171
        content: Role content
172
        
173
    Returns:
174
        Tuple of user link nodes and any error messages
175
    """
176
```
177

178
Usage:
179

180
```rst
181
:github:repo:`user/repository`
182
:github:user:`username`
183
:github:org:`organization`
184
```
185

186
### Node Visitors
187

188
HTML and LaTeX visitors for rendering GitHub nodes in different output formats.
189

190
```python { .api }
191
def visit_issue_node(translator: HTML5Translator, node: IssueNode) -> None:
192
    """
193
    Visit issue node during HTML translation.
194
    
195
    Args:
196
        translator: Sphinx HTML translator
197
        node: Issue node to process
198
    """
199

200
def depart_issue_node(translator: HTML5Translator, node: IssueNode) -> None:
201
    """
202
    Depart issue node during HTML translation.
203
    
204
    Args:
205
        translator: Sphinx HTML translator  
206
        node: Issue node being processed
207
    """
208

209
def visit_issue_node_latex(translator: LaTeXTranslator, node: IssueNode) -> None:
210
    """Visit issue node during LaTeX translation."""
211

212
def depart_issue_node_latex(translator: LaTeXTranslator, node: IssueNode) -> None:
213
    """Depart issue node during LaTeX translation."""
214

215
# Similar visitors for GitHubObjectLinkNode
216
def visit_github_object_link_node(translator: HTML5Translator, node: GitHubObjectLinkNode) -> None: ...
217
def depart_github_object_link_node(translator: HTML5Translator, node: GitHubObjectLinkNode) -> None: ...
218
```
219

220
### Source File Links
221

222
Enhanced source file linking with GitHub integration.
223

224
```python { .api }
225
def source_role(
226
    name: str,
227
    rawtext: str,
228
    text: str, 
229
    lineno: int,
230
    inliner: Inliner,
231
    options: Dict[str, Any] = {},
232
    content: List[str] = []
233
) -> Tuple[List[Node], List[system_message]]:
234
    """
235
    Role for linking to source files on GitHub or in documentation.
236
    
237
    Args:
238
        name: Role name ('source')
239
        rawtext: Raw role text
240
        text: File path
241
        lineno: Line number in document
242
        inliner: Sphinx inliner
243
        options: Role options
244
        content: Role content
245
        
246
    Returns:
247
        Tuple of source link nodes and any error messages
248
    """
249
```
250

251
Usage:
252

253
```rst
254
:source:`path/to/file.py`
255
:source:`module/__init__.py`
256
```
257

258
### Configuration
259

260
GitHub integration requires configuration in your Sphinx `conf.py`:
261

262
```python
263
# Required for issue/pull roles without repository specification
264
github_username = "your-username"
265
github_repository = "your-repository"
266

267
# Optional settings
268
source_link_target = "github"  # or "docs" 
269
github_url = "https://github.com"  # Custom GitHub instance
270
```
271

272
### Error Handling
273

274
The GitHub integration includes proper error handling for API failures and configuration issues:
275

276
```python { .api }
277
class GitHubAPIError(Exception):
278
    """Raised when GitHub API requests fail."""
279

280
class MissingGitHubConfigError(MissingOptionError):
281
    """Raised when required GitHub configuration is missing."""
282
```
283

284
### API Rate Limiting
285

286
The integration includes built-in rate limiting and caching to avoid hitting GitHub API limits:
287

288
- Automatic caching of API responses for 4 hours
289
- Rate limit handling with exponential backoff
290
- Graceful degradation when API is unavailable
291

292
### Advanced Usage
293

294
For more advanced usage scenarios:
295

296
```rst
297
.. note::
298
   
299
   Related to :github:issue:`123` and :github:pull:`456`.
300
   
301
   See :github:repo:`related-org/related-project` for similar functionality.
302
   
303
   Thanks to :github:user:`contributor` for the implementation.
304

305
Cross-repository references:
306
:github:issue:`other-user/other-repo#789`
307
:github:pull:`other-user/other-repo#101`
308
```