4

I'm generating Sphinx documentation and would ideally like for my docstrings to be as readable in code as possible, so I'd like to keep reStructuredText to a minimum, while generating as much of my Sphinx documentation as possible directly from docstrings.

In particular I'd like to be able to keep URLs out of my docstrings where possible, have them where it is not too disturbing, and format link text as code where appropriate. But it's not clear how to do all these things. For example, 

Sadly, `git`_, though it works as a link, does not format `git` as code, 
while ``git``_ generates an error; and `git <http://git-scm.com>`_ 
again does not format `git` while ``git` <http://git-scm.com>`_ is 
again an error.
.. _`git`:  http://git-scm.com

Are there extensions, settings, or other markup I can use so that something compact like 

`git`_

or a substitution like

:git:

generates a code-formatted link?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
orome
  • 45,163
  • 57
  • 202
  • 418
  • 2
    Looks like a duplicate of http://stackoverflow.com/q/4743845/407651. – mzjn Jan 02 '13 at 10:22
  • Not quite, my question is more generally about approaches to creating compact links, but I think my answer ("no", what I've done is about as close as I can get) is [linked](http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible) from that question so: close as a duplicate. – orome Jan 02 '13 at 15:16

0 Answers0