I&#39;m making a framework in which I let developers describe their package using reStructuredText. I want to parse that reStructuredText into HTML so I can show it in a GUI.

I&#39;m familiar with the excellent Sphinx, but I&#39;ve never otherwise parsed reStructuredText. I imagined something like a function that takes a string of reStructuredText, and possibly several additional arguments, and returns a string of HTML.

So I looked into Docutils, which is responsible for parsing reStructuredText. I couldn&#39;t understand at all how to find this function. Documentation on the web is spotty. Many of the functions in the `docutils.parsers.rst` module seemed to be geared toward filenames. I don&#39;t have filenames! I&#39;m just handling strings.

I tried creating a `Parser` and a `Document` and using the `parse` method, but I just get an error about a missing `.tab_width` setting.

Does anyone know how to parse reStructuredText into HTML?

Parsing reStructuredText into HTML

I&#39;m writing some documentation using ReStructuredText (ReST) format for the later web-page generation using Sphinx, and I cannot find a way to write some &quot;bold italic&quot; text. 

There are markers for the so-called &#39;emphasis&#39; (*italic*) and &#39;strong emphasis&#39; (**bold**) text. They are `*italic text*` and `**bold text**` respectively. I also read in some documentation on this format that these formatting markers cannot be simply &quot;nested&quot;. I.e. the `***text***` (or `** *text* **`) does not produce the ***bold italic*** text.
  
Still there probably should be some way to produce a text emphasized both with bold and italic markers, since it is a widespread practice to mark pieces of text that way.

Bold italic in ReStructuredText

Is it possible to strike text through in Restructured Text?

Something that for example renders as a `&lt;strike&gt;` tag when converted to HTML, like: 
&lt;strike&gt;ReSTructuredText&lt;/strike&gt;


ReST strikethrough

I know reStructuredText has this directive:

    .. code:: bash
    
        gedit pohl.m

which renders a code block. Is there some way to get syntax highlighting for inline snippets like this:

    Do edit the file, type ``gedit pohl.m`` into a terminal.

The backticks mark it as code, but I&#39;d like to highlight it with pygments like the block. Is this possible?

Inline code highlighting in reStructuredText

How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?

Adding a cross-reference to a subheading or anchor in another page

I am a great fan of [reStructuredText][0], however the tools that support it are scattered all over the Internet. The [official tool list][1] is incomplete and/or outdated, and can be updated only via commit privileges. For some time there was a comprehensive list at the [Wikipedia reStructuredText page][2], but this apparently &quot;[did not meet the notability guideline for web content][3]&quot; and [was removed][4].

So to put it in a question form: **What tool support can one expect to find when working with reStructuredText, e.g. text editors, Wiki software, converters to and from reStructuredText etc.?**

[0]:http://docutils.sourceforge.net/rst.html
[1]:http://docutils.sourceforge.net/docs/user/links.html
[2]:http://en.wikipedia.org/wiki/ReStructuredText
[3]:http://en.wikipedia.org/wiki/Talk:ReStructuredText#Notability
[4]:http://en.wikipedia.org/wiki/Talk:ReStructuredText#tool_support

reStructuredText tool support

I have a project hosted on GitHub. For this I have written my README using the Markdown syntax in order to have it nicely formatted on GitHub.

As my project is in Python I also plan to upload it to [PyPi][1]. The syntax used for READMEs on PyPi is reStructuredText. 

I would like to avoid having to handle two READMEs containing roughly the same content; so I searched for a markdown to RST (or the other way around) translator, but couldn&#39;t find any. 

The other solution I see is to perform a markdown/HTML and then a HTML/RST translation. I found some ressources for this [here][2] and [here][3] so I guess it should be possible.

Would you have any idea that could fit better with what I want to do?

  [1]: http://pypi.python.org/pypi
  [2]: http://www.siafoo.net/tools/html
  [3]: http://net.tutsplus.com/tutorials/other/vim-essential-plugin-markdown-to-html/

Have the same README both in Markdown and reStructuredText

I am trying to create a properly nested list using the following code (following [Sphinx](http://sphinx.pocoo.org/latest/rest.html#lists-and-quote-like-blocks) and [docutils](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html) docs):

    1. X

      a. U
      b. V
      c. W

    2. Y
    3. Z

I expect this to result in two `OL`s but I get the following output instead:

    &lt;ol class=&quot;arabic simple&quot;&gt; 
      &lt;li&gt;X&lt;/li&gt; 
    &lt;/ol&gt; 

    &lt;blockquote&gt; 
      &lt;div&gt;
        &lt;ol class=&quot;loweralpha simple&quot;&gt; 
          &lt;li&gt;U&lt;/li&gt; 
          &lt;li&gt;V&lt;/li&gt; 
          &lt;li&gt;W&lt;/li&gt; 
        &lt;/ol&gt; 
      &lt;/div&gt;
    &lt;/blockquote&gt; 

    &lt;ol class=&quot;arabic simple&quot; start=&quot;2&quot;&gt; 
      &lt;li&gt;Y&lt;/li&gt; 
      &lt;li&gt;Z&lt;/li&gt; 
    &lt;/ol&gt; 

What am I doing wrong? Is it not possible to get the following result?

    &lt;ol class=&quot;arabic simple&quot;&gt; 
      &lt;li&gt;X
        &lt;ol class=&quot;loweralpha simple&quot;&gt; 
          &lt;li&gt;U&lt;/li&gt; 
          &lt;li&gt;V&lt;/li&gt; 
          &lt;li&gt;W&lt;/li&gt; 
        &lt;/ol&gt; 
      &lt;/li&gt;
      &lt;li&gt;Y&lt;/li&gt; 
      &lt;li&gt;Z&lt;/li&gt; 
    &lt;/ol&gt; 


How to create a nested list in reStructuredText?

How do you format text within a denoted link in reStructuredText?

Specifically, I wish to generate the following HTML from my rst:

    &lt;a href=&quot;http://docs.python.org/library/optparse.html&quot;&gt;&lt;tt&gt;optparse.OptionParser&lt;/tt&gt; documentation documentation&lt;/a&gt;

The result should look like this:

&gt; [`optparse.OptionParser`
&gt; documentation][1]

where the &quot;optparse.OptionParser&quot; portion is in fixed-width font.

I tried

    ```optparse.OptionParser`` &lt;http://docs.python.org/library/optparse.html&gt;`_

however, this gave

    &lt;tt class=&quot;docutils literal&quot;&gt;`optparse.OptionParser&lt;/tt&gt; documentation &amp;lt;&lt;a class=&quot;reference external&quot; href=&quot;http://docs.python.org/library/optparse.html&quot;&gt;http://docs.python.org/library/optparse.html&lt;/a&gt;&amp;gt;`_

which looks like this

&gt; \``optparse.OptionParser`
&gt; documentation
&gt; &lt;http://docs.python.org/library/optparse.html&gt;\`_

  [1]: http://docs.python.org/library/optparse.html

Format text in a link in reStructuredText

Here is what I would like to do:

    1. `link &lt;http://www.google.com&gt;`__
    2. `link &lt;http://www.yahoo.com&gt;`__

To obtain:

    &lt;ol&gt;
    &lt;li&gt;&lt;a href=&quot;http://www.google.com&quot;&gt;link&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;http://www.yahoo.com&quot;&gt;link&lt;/a&gt;&lt;/li&gt;
    &lt;/ol&gt;

The context is a list of publications, where I want them all to have a link marked &quot;DOI&quot; at the end.

However, this seems to fails with:

    &lt;string&gt;:3: (WARNING/2) Duplicate explicit target name: &quot;doi&quot;.

The exact error seems to depend on the version of docutils that I use, but they&#39;ve all failed.

Is there a way to generate multiple links with the same text in restructured text?

How to have same text in two links with restructured text?

Please identify the most popular lightweight markup languages and compare their strengths and weaknesses.  These languages should be general-purpose markup for technical prose, such as for documentation (for example, Haml doesn&#39;t count).

See also: [Markdown versus ReStructuredText][1]

  [1]: https://stackoverflow.com/questions/34276/markdown-versus-restructuredtext

Compare and contrast the lightweight markup languages

I have a module, `errors.py` in which several global constants are defined (note: I understand that Python doesn&#39;t have constants, but I&#39;ve defined them by convention using UPPERCASE).

    &quot;&quot;&quot;Indicates some unknown error.&quot;&quot;&quot;
    API_ERROR = 1

    &quot;&quot;&quot;Indicates that the request was bad in some way.&quot;&quot;&quot;
    BAD_REQUEST = 2

    &quot;&quot;&quot;Indicates that the request is missing required parameters.&quot;&quot;&quot;
    MISSING_PARAMS = 3

Using reStructuredText how can I document these constants? As you can see I&#39;ve listed a docstring above them, but I haven&#39;t found any documentation that indicates to do that, I&#39;ve just done it as a guess.

How to document a module constant in Python?

The comment of HTML is `&lt;!-- .. --&gt;`, how can I make this comment block with restructured text? In order words, how can I comment out some of the lines in restructured text?

How to comment a string in restructured text?

I would like to use a lightweight markup language to take notes in my college classes. 

My editor of choice is gedit, and I found [reStructuredText Tools for Gedit](https://github.com/bittner/gedit-reST-plugin), which will run the reStructuredText processor and render the HTML in a pane in gedit. This is great, and 80% of the way there.

But for many of my classes I need to include math equations or greek characters in my notes. Although I&#39;m not very familiar with LaTeX, my understanding is that it has these capabilities. 

How can I use LaTeX in a reST document? Would the reST document need to be processed into LaTeX, then that rendered into HTML, or is there a better way? Would markdown make this easier? I can modify the gedit plugin if necessary.

Lastly, does anyone do this? Any other suggestions for taking class notes in a plain text editor?

Thanks!

Math in reStructuredText with LaTeX

I&#39;m getting the warning:

    WARNING: document isn&#39;t included in any toctree

for files that exist in the document because they&#39;ve been explicitly included.  So I have the index file:

    .. toctree::
        :maxdepth: 2

       pages/0010-foo
       pages/0020-bar

In the file 0020-bar.rst, I&#39;m specifically including a number of other files, as in:

    .. contents:: :local:

    .. include:: /pages/reference-architecture/technical-considerations/0070-baz.rst

But when I build the project, I still get a warning that 0070-baz.rst isn&#39;t in any toctree, as in:

    /home/nick/Documents/myProject/docs/pages/reference-architecture/technical-considerations/0070-baz.rst:: WARNING: document isn&#39;t included in any toctree

The weird thing is that I can see the content in the output. Is this normal?  Does this warning always appear for files that are explicitly included rather than included via toctree?

WARNING: document isn&#39;t included in any toctree for included file

I have simply no idea on how can I link to another document in the reST file.

I want to link a file named `install.rst` to my quickstart guide in a paragraph. I don&#39;t know how can I achieve this.

Please can you also refer to a great resource from where I can look up syntax for rest. The default quickstart is a little boring and not involves great depth discussion of using rest with sphinx.

The doc in question is : http://todx.rtfd.io

How can I link/reference another reST file in the documentation?

Is there a tool or script which easily merges a bunch of [JAR][1] files into one JAR file? A bonus would be to easily set the main-file manifest and make it executable.

The concrete case is a [Java restructured text tool][2]. I would like to run it with something like:

&gt; java -jar rst.jar

As far as I can tell, it has no dependencies which indicates that it shouldn&#39;t be an easy single-file tool, but the downloaded ZIP file contains a lot of libraries.

          0  11-30-07 10:01   jrst-0.8.1/
        922  11-30-07 09:53   jrst-0.8.1/jrst.bat
        898  11-30-07 09:53   jrst-0.8.1/jrst.sh
       2675  11-30-07 09:42   jrst-0.8.1/readmeEN.txt
     108821  11-30-07 09:59   jrst-0.8.1/jrst-0.8.1.jar
       2675  11-30-07 09:42   jrst-0.8.1/readme.txt
          0  11-30-07 10:01   jrst-0.8.1/lib/
      81508  11-30-07 09:49   jrst-0.8.1/lib/batik-util-1.6-1.jar
    2450757  11-30-07 09:49   jrst-0.8.1/lib/icu4j-2.6.1.jar
     559366  11-30-07 09:49   jrst-0.8.1/lib/commons-collections-3.1.jar
      83613  11-30-07 09:49   jrst-0.8.1/lib/commons-io-1.3.1.jar
     207723  11-30-07 09:49   jrst-0.8.1/lib/commons-lang-2.1.jar
      52915  11-30-07 09:49   jrst-0.8.1/lib/commons-logging-1.1.jar
     260172  11-30-07 09:49   jrst-0.8.1/lib/commons-primitives-1.0.jar
     313898  11-30-07 09:49   jrst-0.8.1/lib/dom4j-1.6.1.jar
    1994150  11-30-07 09:49   jrst-0.8.1/lib/fop-0.93-jdk15.jar
      55147  11-30-07 09:49   jrst-0.8.1/lib/activation-1.0.2.jar
     355030  11-30-07 09:49   jrst-0.8.1/lib/mail-1.3.3.jar
      77977  11-30-07 09:49   jrst-0.8.1/lib/servlet-api-2.3.jar
     226915  11-30-07 09:49   jrst-0.8.1/lib/jaxen-1.1.1.jar
     153253  11-30-07 09:49   jrst-0.8.1/lib/jdom-1.0.jar
      50789  11-30-07 09:49   jrst-0.8.1/lib/jewelcli-0.41.jar
     324952  11-30-07 09:49   jrst-0.8.1/lib/looks-1.2.2.jar
     121070  11-30-07 09:49   jrst-0.8.1/lib/junit-3.8.1.jar
     358085  11-30-07 09:49   jrst-0.8.1/lib/log4j-1.2.12.jar
      72150  11-30-07 09:49   jrst-0.8.1/lib/logkit-1.0.1.jar
     342897  11-30-07 09:49   jrst-0.8.1/lib/lutinwidget-0.9.jar
    2160934  11-30-07 09:49   jrst-0.8.1/lib/docbook-xsl-nwalsh-1.71.1.jar
     301249  11-30-07 09:49   jrst-0.8.1/lib/xmlgraphics-commons-1.1.jar
      68610  11-30-07 09:49   jrst-0.8.1/lib/sdoc-0.5.0-beta.jar
    3149655  11-30-07 09:49   jrst-0.8.1/lib/xalan-2.6.0.jar
    1010675  11-30-07 09:49   jrst-0.8.1/lib/xercesImpl-2.6.2.jar
     194205  11-30-07 09:49   jrst-0.8.1/lib/xml-apis-1.3.02.jar
      78440  11-30-07 09:49   jrst-0.8.1/lib/xmlParserAPIs-2.0.2.jar
      86249  11-30-07 09:49   jrst-0.8.1/lib/xmlunit-1.1.jar
     108874  11-30-07 09:49   jrst-0.8.1/lib/xom-1.0.jar
      63966  11-30-07 09:49   jrst-0.8.1/lib/avalon-framework-4.1.3.jar
     138228  11-30-07 09:49   jrst-0.8.1/lib/batik-gui-util-1.6-1.jar
     216394  11-30-07 09:49   jrst-0.8.1/lib/l2fprod-common-0.1.jar
     121689  11-30-07 09:49   jrst-0.8.1/lib/lutinutil-0.26.jar
      76687  11-30-07 09:49   jrst-0.8.1/lib/batik-ext-1.6-1.jar
     124724  11-30-07 09:49   jrst-0.8.1/lib/xmlParserAPIs-2.6.2.jar

As you can see, it is somewhat desirable to not need to do this manually.

So far I&#39;ve only tried AutoJar and ProGuard, both of which were fairly easy to get running. It appears that there&#39;s some issue with the constant pool in the JAR files.

Apparently jrst is slightly broken, so I&#39;ll make a go of fixing it. The [Maven][3] `pom.xml` file was apparently broken too, so I&#39;ll have to fix that before fixing jrst ... I feel like a bug-magnet :-)

----

Update: I never got around to fixing this application, but I checked out [Eclipse][4]&#39;s &quot;Runnable JAR export wizard&quot; which is based on a fat JAR. I found this very easy to use for deploying my own code.

Some of the other excellent suggestions might be better for builds in a non-Eclipse environment, oss probably should make a nice build using [Ant][5]. (Maven, so far has just given me pain, but others love it.)

  [1]: http://en.wikipedia.org/wiki/JAR_%28file_format%29
  [2]: http://jrst.labs.libre-entreprise.org/en/user/functionality.html
  [3]: http://en.wikipedia.org/wiki/Apache_Maven
  [4]: http://en.wikipedia.org/wiki/Eclipse_%28software%29
  [5]: http://en.wikipedia.org/wiki/Apache_Ant


Easiest way to merge a release into one JAR file

I am using the *Sphinx* `autodoc` feature to generate documentation based on the docstrings of my Python library.

The syntax for cross referencing is found [here][1]


A label must precede the section in order to allow that section to be referenced from other areas of the documentation.

What I have is a .rst (ReStructeredText) file for one of my classes. It uses
    
    .. autoclass:: classname
        :members:

To generate documentation for the class.

My question is, how would I reference the auto-generated methods of the class from another .rst document in the documentation? If I try to place a label within the method&#39;s docstring, Sphinx complains. If I try to place a label before the method heading, Sphinx doesn&#39;t recognize it.

Is there a simple way to do this, or will I have to explicitly write in my class file the method name and precede that with a label?

Here is an example a reference within the [Python documentation[2] doing what I need (I am assuming it used the autodoc feature, though I don&#39;t know for sure)

  [1]: http://sphinx-doc.org/markup/inline.html#ref-role
  [2]: http://docs.python.org/2.7/library/textwrap.html#textwrap.TextWrapper.wrap

How would I cross-reference a function generated by autodoc in Sphinx?

I&#39;m using [reStructuredText] and I&#39;d like to add HTML encoding an interactive flash-type animation through the `&lt;embed&gt;` tag. From my .rst document, how can I specify the position of this arbitrary chunk of HTML?  Something like:

&lt;!-- Language: lang-none --&gt;

      .. html ::
    
      &lt;embed&gt;
      ... more html here ...
      &lt;/embed&gt;

Does this feature exist?  thanks.


[reStructuredText]: http://docutils.sourceforge.net/rst.html

How to embed HTML in restructured text file?

I uploaded a package to PyPi using:

    python setup.py register -r pypi
    python setup.py sdist upload -r pypi


I&#39;m trying to modify the description, I wrote (**please don&#39;t edit the formatting of the following piece of code, I made it on purpose to demonstrate my problem**):

    **my plugin**
    
    This plugin enables you to ... For example:
    ```python
    @attr(section=&#39;MySection&#39;, id=1)
    def test_function(self):
        &quot;&quot;&quot;
        Bla bla bla
        &quot;&quot;&quot;
        pass
    ```

However, the text appears as it is, *without* the markdown formatting. What am I doing wrong?

How to make PyPi description Markdown work?

How to include a local table of contents into Sphinx doc?

I tried 

    .. toc:: 


But that doesn&#39;t seem to have any effect: nothing is inserted in the document.

Basically I need links to the sections in the current page to be placed at a certain location of each page.

Is this possible?

How to include a local table of contents into Sphinx doc?

How can I create a linked image with reStructuredText?

I&#39;ve found

    .. image:: /path/to/image.jpg

for images, and external hyperlinks like 

    &#39;Python &lt;http://www.python.org/&gt;&#39;_

for links, but I don&#39;t know how to combine them or if that is at all possible.

linked image in reStructuredText

So, reStructuredText is
[the recommended way](https://www.python.org/dev/peps/pep-0287) for Python code
documentation, if you try hard enough, you can
[find in the sphinx documentation](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#python-signatures)
how to normalize your function signature documentation. All given examples are
single-line, but what if a parameter description is multi-line like the following
?

    def f(a, b):
        &quot;&quot;&quot; Does something with a and b

        :param a: something simple
        :param b: well, it&#39;s not something simple, so it may require more than eighty
                  chars
        &quot;&quot;&quot;

What is the syntax/convention for that ? Should I indent or not ? will it break reSTructuredText rendering ?


Multi-line description of a parameter description in python docstring

I&#39;m starting an open source Python project shortly and I&#39;m trying to decide in advance how to write my docstrings. The obvious answer would be using reStructuredText and Sphinx with `autodoc`, because I *really* like the idea of simply properly documenting my code in my docstrings then have Sphinx automatically construct an API doc for me.

The problem is the reStructuredText syntax it uses - I think it&#39;s completely unreadable before it&#39;s rendered. For instance:


	:param path: The path of the file to wrap
	:type path: str
	:param field_storage: The :class:`FileStorage` instance to wrap
	:type field_storage: FileStorage
	:param temporary: Whether or not to delete the file when the File instance
		is destructed
	:type temporary: bool

You have to *really* slow down and take a minute to make any sense out of that syntactic jumble. I like much more the Google way ([Google Python Style Guide][1]), which counterpart to the above looks like this:

&lt;pre&gt;
Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The FileStorage instance to wrap
    temporary (bool): Whether or not to delete the file when the File
        instance is destructed
&lt;/pre&gt;

**Way** nicer! But of course, Sphinx will have none of that and renders all the text after `Args:` in one long line.

So to summarize - before I go and defile my code base with this reStructuredText syntax I would like to know if there are any real alternatives to using it and Sphinx, short of just writing my own API doc. For instance, is there an extension for Sphinx that handles Google Style Guide&#39;s docstring style?

  [1]: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html

All Restructuredtext Solutions on Gang of Coders

Total of 24 Restructuredtext Solutions