restructuredtext

问题 I'm wondering if it's possible to use a dynamic path in a Sphinx and/or RST ..include:: directive? My reason for this is I have some developer documentation generated by Sphinx in one repo, but we have a bunch of unit tests in another repo that we want to include in the docs. If I know the path to the file in the other repo, it's pretty standard, like this: Some text in my RST file .. include:: ../path/to/other/repo/file.py :code: python Some more text The problem is the relative path to the

问题 The Python docs say that "the markup used for the Python documentation is reStructuredText". My question is: How is a block comment supposed to be written to show multiple return values? def func_returning_one_value(): """Return just one value. :returns: some value :rtype: str """ def func_returning_three_values(): """Return three values. How do I note in reStructuredText that three values are returned? """ I've found a tutorial on Python documentation using reStructuredText, but it doesn't

问题 How can I substitute a container directive ? The following doesn't work: .. |sub| container:: Some text here .. image:: img/some_image.png Some other text here The error message is WARNING: Substitution definition "sub" empty or invalid. 回答1: This is not possible. ReST substitutions apply to inline text (single paragraphs), but a container is a block element. And if you try .. |sub| replace:: container:: Some text here .. image:: img/some_image.png Some other text here you will get ERROR:

问题 How can I set an anchor reference at an arbitrary line in ReST using Sphinx? To be more clear, here is an example: A title with an anchor ---------------------- some stuff this will create a heading A title with an anchor and add an extra on-hover ¶ character at the end of the line, which will be an anchor reference to that line/heading. Now in the following case... ``some arbitrary line`` this is actually a definition ...I want to have an anchor for some arbitrary line , the same way as for

问题 I am trying to use a jQuery lightBox implementation on my website that is generated from reStructuredText. The lightBox takes the title of the link around the images as the caption of the image in the lightBox display. However, I can't seem to find a way in reStructuredText of providing a title attribute on a link - does anyone know of a way of doing this? My images are defined like so: .. image:: image001.thumb.jpg :alt: Some alt text here :target: image001.jpg So I can add an alt attribute,

问题 I prefer to document each parameter (as needed) on the same line where I declare the parameter in order to apply D.R.Y. If I have code like this: def foo( flab_nickers, # a series of under garments to process has_polka_dots=False, needs_pressing=False # Whether the list of garments should all be pressed ): ... How can I avoid repeating the parameters in the doc string and retain the parameter explanations? I want to avoid: def foo( flab_nickers, # a series of under garments to process has

问题 Is there a way to input a newline into a table cell? For example, say I have a table like this: +----------+----------+----------+ | Header 1 | Header 2 | Header 3 | +==========+==========+==========+ | Item 1 | | | | Item 2 | | | +----------+----------+----------+ I want the above to create a table with two rows, three columns, and the second row, first column to display Item 1 and Item 2 on separate lines. I have tried the line blocks syntax |, but it doesn't work inside a table cell. I can

问题 I have a similar question to this, except for Sphinx and RST. Namely, I would like to prevent text from being hyphenated at the end of the line. For example I want this: This is my long sent- ence. To be: This is my long sentence. How do I do this? 回答1: Hyphenation is implemented by the stylesheet basic.css in the Sphinx theme "basic". div.body p, div.body dd, div.body li, div.body blockquote { -moz-hyphens: auto; -ms-hyphens: auto; -webkit-hyphens: auto; hyphens: auto; } You can override

问题 I have this table in ReST markup: +---------------------------+-----------------------------------------------------------------+ | Option Line Kind | Distinguishing Characteristic | +===========================+=================================================================+ | **Reference** | The option name is called a (node) reference, if the value\ | | | of an option is a predefined keyword for the current node\ | | | class. Because the option's value is a keyword, it can not\ | | | be

问题 As far as I can tell, it is not possible to create a literal text block (e.g. with the code-block directive) that starts or ends with a blank line, because this would be ambiguous with regard to the reStructuredText syntax. That's OK. But now I want to create a custom directive that uses docutils 's literal_block() node, and I want (within the code of my directive) to add empty lines at the beginning and/or end of the directive's contents. Since this isn't possible in reStructuredText syntax,