I know of three main languages used commonly in the greater programming and tech community: Textile, Markdown, and reStructuredText. All three can be learned in a couple of hours or “winged” with the cheat sheet nearby. Textile Used by Redmine and the Ruby community 113 questions currently tagged on Stack Overflow The most similar to … Read more
This construct: Here you have |optparse.OptionParser|_. .. |optparse.OptionParser| replace:: “optparse.OptionParser“ documentation .. _optparse.OptionParser: http://docs.python.org/library/optparse.html produces this HTML (some linebreaks added): <p>Here you have <a class=”reference external” href=”http://docs.python.org/library/optparse.html”> <tt class=”docutils literal”><span class=”pre”>optparse.OptionParser</span></tt> documentation</a>. </p> I realize that this is not exactly what you asked for, but maybe it’s close enough. See also http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible.
The warning (WARNING/2) Duplicate explicit target name:foo occurs when you use the same text for two different links in “Named hyperlink references”: `Foo <http://example.org>`_ `Foo <http://example.com>`_ To circumvent it, use anonymous hyperlink references with double underscores: `Foo <http://example.org>`__ `Foo <http://example.com>`__ This works without a warning on docutils 0.8.1.
Make sure the nested list is indented to the same level as the text of the parent list (or three characters, whichever is greater), like this: 1. X a. U b. V c. W 2. Y 3. Z Then you’ll get the output you expected.
Salvaging (and extending) the list from an old version of the Wikipedia page: Documentation Primer Cheat Sheet Quick Reference Implementations Although the reference implementation of reStructuredText is written in Python, there are reStructuredText parsers in other languages too. Python – Docutils The main distribution of reStructuredText is the Python Docutils package. It contains several conversion … Read more
I would recommend Pandoc, the “swiss-army knife for converting files from one markup format into another” (check out the diagram of supported conversions at the bottom of the page, it is quite impressive). Pandoc allows markdown to reStructuredText translation directly. There is also an online editor here which lets you try it out, so you … Read more
The expression “reST/Sphinx” makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I’m going to cover both since people using RST are likely to run into both cases at some point: Sphinx Besides the domain-specific directives … Read more
Having looked into this some more I stumbled upon the document reStructuredText Interpreted Text Roles. From this document: Interpreted text uses backquotes (`) around the text. An explicit role marker may optionally appear before or after the text, delimited with colons. For example: This is `interpreted text` using the default role. This is :title:`interpreted text` … Read more