restructuredtext

问题 I'm documenting my Python code using Sphinx, and read in the Python developer's guide (and I think elsewhere as well) that reST files use an indentation of 3 spaces: All reST files use an indentation of 3 spaces; no tabs are allowed. This is the case for the example I copied for my index file, and some other files where my IDE picked up the 3-space indentation and used it for the whole page. The sphinx-apidoc extension also uses 3 spaces for the modules.rst file it builds. On the other hand,

问题 I'm writing some documentation using Sphinx. Is there a way to format headings within a page which do not become part of the TOC? Ideally with some hierarchy that is reflected in formatting? E.g. I want to do My page TOC heading =================== Subheading (not in TOC, and should be formatted e.g. smaller than the heading) +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Sub-subheading (not in TOC, and formatted e.g. smaller than the subheading) ###############################

问题 I know how to create an external hyperlink with customized text. `My cool link <http://www.asdf.com>`_ But I want to link to an internal reference. .. _foo: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. So I'd like to do something like `My cool internal link <foo>`_ But this doesn't work. 回答1: Solution: `My cool internal link <foo_>`_ 回答2: Use 2 underscores on text and 1 undescore on link target, example: `My cool

问题 I know how to create an external hyperlink with customized text. `My cool link <http://www.asdf.com>`_ But I want to link to an internal reference. .. _foo: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. So I'd like to do something like `My cool internal link <foo>`_ But this doesn't work. 回答1: Solution: `My cool internal link <foo_>`_ 回答2: Use 2 underscores on text and 1 undescore on link target, example: `My cool

问题 I am trying to create a properly nested list using the following code (following Sphinx and docutils 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: <ol class="arabic simple"> <li>X</li> </ol> <blockquote> <div> <ol class="loweralpha simple"> <li>U</li> <li>V</li> <li>W</li> </ol> </div> </blockquote> <ol class="arabic simple" start="2"> <li>Y</li> <li>Z</li> </ol> What am I doing wrong? Is it not possible to get the following

问题 I am trying to create a properly nested list using the following code (following Sphinx and docutils 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: <ol class="arabic simple"> <li>X</li> </ol> <blockquote> <div> <ol class="loweralpha simple"> <li>U</li> <li>V</li> <li>W</li> </ol> </div> </blockquote> <ol class="arabic simple" start="2"> <li>Y</li> <li>Z</li> </ol> What am I doing wrong? Is it not possible to get the following

问题 I've been documenting a software package using Sphinx and reStructuredText. Within my documents, there are some long code snippets. I want to be able to have them hidden as default, with a little "Show/Hide" button that would expand them (Example). Is there a standard way to do that? 回答1: I think the easiest way to do this would be to create a custom Sphinx theme in which you tell certain html elements to have this functionality. A little JQuery would go a long way here. If, however you want

问题 I have a list item in my rst file that I would like to put a literal block into, but I am unable to get the literal block to end properly. This is my rst: 1. Item 1 (not literal) 2. Item 2:: MyCode.example() Description of the code shown above (not literal) I would like the paragraph starting with Description to be outside the literal block above it, but still part of list item #2. The only workaround I have been able to come up with is this: 1. Item 1 (not literal) 2. Item 2: :: MyCode

问题 How can I do a substitution in an admonition? For example: |p| account .. note:: **Been using |p| separately and now integrating?** In my sphinx conf.py I define a replacement rule which gets appended to the rst file prior to interpretation (at least that is how I understand it): rst_epilog = '.. |p| replace:: Labnext' My first substitution in the paragraph works without fail. However the substitution in the note directive isn't applied. Any work arounds? Thanks, Mike 回答1: The substitution in

问题 Here's an example Sphinx doc: https://github.com/django-tastypie/django-tastypie/blob/v0.13.2/docs/release_notes/v0.13.2.rst I'd like commit SHA's, issue numbers, and @mentions to be hyperlinked. Anyway to do that automatically? 回答1: I'd suggest checking out the Sphinx Extension library at http://sphinxext-survey.readthedocs.org/en/latest/changelog-version-control.html. Specifically, I believe these two extensions may provide you at least some of the support you're looking for (sans the