Repository: pandas-dev/pandas

Issue:
Create sphinx extension to handle github issue/changeset links
Add a sphinx extension, such that it is easier to link to github issue or changeset in the rst docs.

Idea comes from [pycon 2013](http://pyvideo.org/video/1703/better-documentation-through-automation-creating) and the [code](https://bitbucket.org/dhellmann/sphinxcontrib-bitbucket) already exists for bitbucket. Maybe also for github somewhere?

This way writing e.g

```
:issue:`GH1234` 
```

wil expand to

```
`GH1234 <https://github.com/pydata/pandas/issues/1234>`__
```



Discussion:
oh yes please. the merge conflicts in RELEASE.rst are a constant annoyance.

will have a pr for this tonight, @y-p should i email doug hellmann and ask about the license? it says you can do whatever you want as long as you include his license.

Looks like two clause BSD, should be fine, just put a copy in LICENSES/.
Regardless of license, a courtesy email to let him know it's useful is always nice,
if you like.

Be aware that RELEASE.rst is not currently processed by sphinx afaict,
so right now it's not a solution for that, unless that's moved into the documentation
and users are pointed to the doc site.

thanks. will send the email. this does clear up the release notes conflicts even though those are usually bursty, i.e., lots of merge conflicts clustered around one of them at a particular point in time.

@cplcloud did you get feedback from Doug Hellmann?

@lodagro no i ended up beating my head against a wall and didn't go back to it yet, i thought i would send the email when i succeeded in doing something with it. i ended up getting something that was workable i just couldn't figure out how to keep the current formatting....i will tyr to get this for 0.12, but i can't make any promises 

@cpcloud no pressure, i was just curious.

@lodagro looks like [ipython has this already](https://github.com/ipython/ipython/blob/694fba752b1e384f26fe554f64a22f9ef243ca60/docs/sphinxext/github.py) should we use it?

Great find! I haven`t tried it but it looks exactly the same idea. If it is ok from license point of view, sure why not use it.

got it working. will send email to Doug Hellmann. 

minor point: ipython convention uses `#3907` for their issue numbers whereas pandas uses `GH3907`, should we use the current convention or convert to the ipython convention? i kind of like using the pound sign but some may want to stick with current way.

i will also convert all the docs with issue mentions and the references at the bottom.

must also implore contributors and current devs to use this new way of noting issues.

I think you need to accept both conventions.....

it's more of an issue about how we want the output to appear...how it appears on the page is hard-coded into the extension

can you give an example of both ways?

sure. currently they appear like this

![new-ext-old-style](https://f.cloud.github.com/assets/417981/675639/bbc7f6cc-d8f6-11e2-88e1-8729ac25f40e.png)

whereas the new version appears like this by default

![new-ext-pound](https://f.cloud.github.com/assets/417981/675643/cea2bf02-d8f6-11e2-8196-909522f7fc5f.png)

(parens are not part of the sphinx markup)

i think we should choose one, i think to enable the option to switch them you need to add a sphinx role which imo is not worth the trouble

btw `RELEASE.rst` is currently only processed by GitHub correct?


Resolving patch:
diff --git a/doc/source/conf.py b/doc/source/conf.py
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -243,8 +243,6 @@
 
 # extlinks alias
 extlinks = {'issue': ('https://github.com/pydata/pandas/issues/%s',
-                      'issue '),
-            'pull request': ('https://github.com/pydata/pandas/pulls/%s',
-                             'pull request '),
-            'wiki': ('https://github.com/pydata/pandas/pulls/%s',
+                      'GH'),
+            'wiki': ('https://github.com/pydata/pandas/wiki/%s',
                      'wiki ')}


Test patch: