If you have a look at :ref: documentation in its official web site about inline markups: :ref: To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work label names must be unique throughout the entire documentation … I think (as @Kevin Horn) it’s no possible right … Read more
From the Sphinx documentation: The default role (`content`) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the default_role config value to set it to a known role. As a matter of personal preference, when writing Python docstrings, I use interpreted text (single backquotes) … Read more
I didn’t find anything which could take reStructuredText files and convert them to Markdown except for Pandoc, so I wrote a custom writer for Docutils (the reference implementation of reStructuredText and what Sphinx is built upon). The code is available on GitHub. Note that it is only an initial implementation: it handles any reStructuredText document … Read more
In the latest versions of Sphinx (1.3+), numbering figures and referencing them from text got a bit easier as support for it is now built-in. In your text, you can do something like: .. _label: .. figure:: images/figure.* At :numref:`label` you can see… The end result should be something like “At Fig 1.1 you can … Read more
Figured it out. The following inserts a relative reference to the document js/index.html: `Javascript API <js/index.html>`_
PyPI will not read your package distributions for the image. You have to use the image’s external link, for example: .. image:: https://raw.githubusercontent.com/greyli/flask-share/master/images/demo.png If you are using Markdown description, use this:  Be sure to replace the URL in the above examples with your image URL, here I use the image hosted by GitHub, the … Read more
I was surprised that you could not simply write .rst stands for **r**e**s**tructured **t**ext. but the reStructuredText specification indeed states that inline markup must be followed by white-space or one of – . , : ; ! ? \ / ‘ ” ) ] } or >, so the above string of reStructuredText is not … Read more
To open a page in a new window or tag you can add the attribute target=”_blank” to your hyperlink although I’m not sure how you can add attributes to inline hyperlinks in reStructuredText. However, from the Docutils FAQ, is nested inline markup possible, you can use the raw directive to include raw HTML into your … Read more
I found this method working First, you have the role. .. role:: red An example of using :red:`interpreted text` It translates into as follows. <p>An example of using <span class=”red”>interpreted text</span></p> Now, you have the red class, you can use CSS for changing colors. .red { color:red; }
The other answers are great. But I thought I (the OP) ought to share what I do these days (a year or two after the question). I use Sphinx and its Markdown extension. Do the following: TL;DR: See Gist snippet. Sphinx-markdown-builder You need sphinx-markdown-builder python module. pip install sphinx sphinx-markdown-builder; Run Sphinx Not the autodoc, … Read more