##// END OF EJS Templates
add github extension for easy links to issues/pulls....
MinRK -
Show More
@@ -0,0 +1,155 b''
1 """Define text roles for GitHub
2
3 * ghissue - Issue
4 * ghpull - Pull Request
5 * ghuser - User
6
7 Adapted from bitbucket example here:
8 https://bitbucket.org/birkenfeld/sphinx-contrib/src/tip/bitbucket/sphinxcontrib/bitbucket.py
9
10 Authors
11 -------
12
13 * Doug Hellmann
14 * Min RK
15 """
16 #
17 # Original Copyright (c) 2010 Doug Hellmann. All rights reserved.
18 #
19
20 from docutils import nodes, utils
21 from docutils.parsers.rst.roles import set_classes
22
23 def make_link_node(rawtext, app, type, slug, options):
24 """Create a link to a github resource.
25
26 :param rawtext: Text being replaced with link node.
27 :param app: Sphinx application context
28 :param type: Link type (issue, changeset, etc.)
29 :param slug: ID of the thing to link to
30 :param options: Options dictionary passed to role func.
31 """
32
33 try:
34 base = app.config.github_project_url
35 if not base:
36 raise AttributeError
37 if not base.endswith('/'):
38 base += '/'
39 except AttributeError, err:
40 raise ValueError('github_project_url configuration value is not set (%s)' % str(err))
41
42 ref = base + type + '/' + slug + '/'
43 set_classes(options)
44 prefix = "#"
45 if type == 'pull':
46 prefix = "PR " + prefix
47 node = nodes.reference(rawtext, prefix + utils.unescape(slug), refuri=ref,
48 **options)
49 return node
50
51 def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
52 """Link to a GitHub issue.
53
54 Returns 2 part tuple containing list of nodes to insert into the
55 document and a list of system messages. Both are allowed to be
56 empty.
57
58 :param name: The role name used in the document.
59 :param rawtext: The entire markup snippet, with role.
60 :param text: The text marked with the role.
61 :param lineno: The line number where rawtext appears in the input.
62 :param inliner: The inliner instance that called us.
63 :param options: Directive options for customization.
64 :param content: The directive content for customization.
65 """
66
67 try:
68 issue_num = int(text)
69 if issue_num <= 0:
70 raise ValueError
71 except ValueError:
72 msg = inliner.reporter.error(
73 'GitHub issue number must be a number greater than or equal to 1; '
74 '"%s" is invalid.' % text, line=lineno)
75 prb = inliner.problematic(rawtext, rawtext, msg)
76 return [prb], [msg]
77 app = inliner.document.settings.env.app
78 #app.info('issue %r' % text)
79 if 'pull' in name.lower():
80 category = 'pull'
81 elif 'issue' in name.lower():
82 category = 'issue'
83 else:
84 msg = inliner.reporter.error(
85 'GitHub roles include "ghpull" and "ghissue", '
86 '"%s" is invalid.' % name, line=lineno)
87 prb = inliner.problematic(rawtext, rawtext, msg)
88 return [prb], [msg]
89 node = make_link_node(rawtext, app, category, str(issue_num), options)
90 return [node], []
91
92 def ghuser_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
93 """Link to a GitHub user.
94
95 Returns 2 part tuple containing list of nodes to insert into the
96 document and a list of system messages. Both are allowed to be
97 empty.
98
99 :param name: The role name used in the document.
100 :param rawtext: The entire markup snippet, with role.
101 :param text: The text marked with the role.
102 :param lineno: The line number where rawtext appears in the input.
103 :param inliner: The inliner instance that called us.
104 :param options: Directive options for customization.
105 :param content: The directive content for customization.
106 """
107 app = inliner.document.settings.env.app
108 #app.info('user link %r' % text)
109 ref = 'https://www.github.com/' + text
110 node = nodes.reference(rawtext, text, refuri=ref, **options)
111 return [node], []
112
113 def ghcommit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
114 """Link to a GitHub commit.
115
116 Returns 2 part tuple containing list of nodes to insert into the
117 document and a list of system messages. Both are allowed to be
118 empty.
119
120 :param name: The role name used in the document.
121 :param rawtext: The entire markup snippet, with role.
122 :param text: The text marked with the role.
123 :param lineno: The line number where rawtext appears in the input.
124 :param inliner: The inliner instance that called us.
125 :param options: Directive options for customization.
126 :param content: The directive content for customization.
127 """
128 app = inliner.document.settings.env.app
129 #app.info('user link %r' % text)
130 try:
131 base = app.config.github_project_url
132 if not base:
133 raise AttributeError
134 if not base.endswith('/'):
135 base += '/'
136 except AttributeError, err:
137 raise ValueError('github_project_url configuration value is not set (%s)' % str(err))
138
139 ref = base + text
140 node = nodes.reference(rawtext, text[:6], refuri=ref, **options)
141 return [node], []
142
143
144 def setup(app):
145 """Install the plugin.
146
147 :param app: Sphinx application context.
148 """
149 app.info('Initializing GitHub plugin')
150 app.add_role('ghissue', ghissue_role)
151 app.add_role('ghpull', ghissue_role)
152 app.add_role('ghuser', ghuser_role)
153 app.add_role('ghcommit', ghcommit_role)
154 app.add_config_value('github_project_url', None, 'env')
155 return
@@ -44,6 +44,7 b' extensions = ['
44 44 'inheritance_diagram',
45 45 'ipython_console_highlighting',
46 46 'numpydoc', # to preprocess docstrings
47 'github', # for easy GitHub links
47 48 ]
48 49
49 50 # Add any paths that contain templates here, relative to this directory.
@@ -59,6 +60,9 b" master_doc = 'index'"
59 60 project = 'IPython'
60 61 copyright = '2008, The IPython Development Team'
61 62
63 # ghissue config
64 github_project_url = "https://github.com/ipython/ipython"
65
62 66 # The default replacements for |version| and |release|, also used in various
63 67 # other places throughout the built documents.
64 68 #
General Comments 0
You need to be logged in to leave comments. Login now