Consider the following list in ReStructuredText:
Broken list example
-------------------
#. First do spam
#. Then do ``eggs``
.. note::
Nobody expects the Spanish Inquisistion
#. The list restarts after the note
When the list is compiled in Sphinx, the number after the note are reset to 1:
Any idea how to continue the numbered list after a note section?
The discontinuity of the list is caused by the note being a standalone element, not a child of the second numbered list element. To prevent the discontinuity of the list, start the note directive at the same indentation (in this case, 3 spaces) as the the text of the intended parent numbered list element. So instead of your sample reStructuredText, try this:
Fixed list example
------------------
#. First do spam
#. Then do ``eggs``
.. note::
Nobody expects the Spanish Inquisistion
#. Then do spam and ``eggs``.
This is one of those things about reStructuredText that's neither easy to spot, nor particularly well documented; see this question on nested lists for a closely-related problem.
Related
In Sphinx (the ReStructuredText publishing system), are there any obscure rules that limit what a literal block can contain?
Background: My document contains many literal blocks that follow a double-colon paragraph, like this:
Background:... follow a double-colon paragraph, like this::
$ sudo su
# echo ttyS0,115200 > /sys/module/kgdboc/parameters/kgdboc
This block (with a different preceding paragraph) is one of the ones that issues an error: "WARNING: Inconsistent literal block quoting." The message indicates that the error is in the "echo" line. In the HTML output the literal block contains only the "sudo" line; the "echo" line is treated as ordinary text.
I haven't been able to identify any common property in the lines that report errors, or anything that distinguishes them, as a class, from lines in other literal blocks that don't get errors.
I stripped down the project to isolate the problem, and I identified it that way.
I had a numbered list item that contained a double-colon literal block that was indented only as far as the list item's text, like this:
2. Set up the... directory::
$ A Linux command
$ Another Linux command
$ And ANOTHER Linux command
$ etc.
When I indented the literal block further, the problem went away.
I was misled by two things:
The message does not point to the first line in the literal block, but to some apparently random line within it. In the case above, it pointed to the fifth line (out of eight) in the block!
In most cases this form of indention, although incorrect, works just fine.
Isolating the problem is a brute-force method of solving it, but is often effective when deduction fails. I'll keep that in mind in the future.
#. List number one
#. Part two
.. note:: adding some note
#. part three
Doing the above causes the spacing or format, in the numbered list to change when compared to a numbered list without a note. For clarity, the text becomes this:
1. List number one
2. List number two
NOTE
3. Part three
Rather than doing this:
1. List number one
2. Part Two
NOTE
3. Part three
Is this a problem with Sphinx, or is it a theme issue?
Whitespace has meaning in reStructuredText. Directives within a bulleted list require blank lines around them, similar to nested lists.
#. List number one
#. Part two
.. note:: adding some note
#. part three
Consider the following list in ReStructuredText:
Broken list example
-------------------
#. First do spam
#. Then do ``eggs``
.. note::
Nobody expects the Spanish Inquisistion
#. The list restarts after the note
When the list is compiled in Sphinx, the number after the note are reset to 1:
Any idea how to continue the numbered list after a note section?
The discontinuity of the list is caused by the note being a standalone element, not a child of the second numbered list element. To prevent the discontinuity of the list, start the note directive at the same indentation (in this case, 3 spaces) as the the text of the intended parent numbered list element. So instead of your sample reStructuredText, try this:
Fixed list example
------------------
#. First do spam
#. Then do ``eggs``
.. note::
Nobody expects the Spanish Inquisistion
#. Then do spam and ``eggs``.
This is one of those things about reStructuredText that's neither easy to spot, nor particularly well documented; see this question on nested lists for a closely-related problem.
Example code:
let interestingNumbers = [
"Prime":[2,3,5,7,11,13],
"Fibonacci":[1,1,2,3,5,8],
"Square":[1,4,9,16,25]`,`
]
Question: after "Square:[1,4,9,16,25]", there is a comma(sample code from Apple Swift reference guide book), when I get rid of it, I didn't get any error messages from Xcode, is this just convention at all ? (I remember there is a nil after array or dictionary in objective-C
This is because a comma after the last element in a dictionary is optional.
Consider the simpler example:
let letters = ["A":1,
"B":2,
"C":3
]
A comma placed after the last element, "C":3, is acceptable, but optional.
I believe that there is no specific convention regarding the final comma - some may prefer it as it allows you to add items on following lines without modifying the above line to add the comma (makes source control review simpler). I often leave commas on the last element in an enum declaration for the same reason.
If you know you are likely to add more elements in the future, then having the comma would simplify the source diff in a code review (one added line instead of one removed line and two added lines). I would use the comma where you know you're going to add elements later, and omit in if the list of items is final.
I'm using Sphinx to document a command line utility written in Python. I want to be able to document a command line option, such as --region like this:
**--region** <region_name>
in ReST and then use Sphinx to to generate my HTML and man pages for me.
This works great when generating man pages but in the generated HTML, the -- gets turned into - which is incorrect. I have found that if I change my source ReST document to look like this:
**---region** <region_name>
The HTML generates correctly but now my man pages have --- instead of --. Also incorrect.
I've tried escaping the dashes with a backslash character (e.g. \-\-) but that had no effect.
Any help would be much appreciated.
This is a configuration option in Sphinx that is on by default: the html_use_smartypants option (http://sphinx-doc.org/config.html?highlight=dash#confval-html_use_smartypants).
If you turn off the option, then you will have to use the Unicode character '–' if you want an en-dash.
With
**-\\-region** <region_name>
it should work.
In Sphinx 1.6 html_use_smartypants has been deprecated, and it is no longer necessary to set html_use_smartypants = False in your conf.py or as an argument to sphinx-build. Instead you should use smart_quotes = False.
If you want to use the transformations formerly provided by html_use_smartypants, instead it is recommended to use smart_quotes, e.g., smart_quotes = True.
Note that at the time of this writing Read the Docs pins sphinx==1.5.3, which does not support the smart_quotes option. Until then, you'll need to continue using html_use_smartypants.
EDIT It appears that Sphinx now uses smartquotes instead of docutils smart_quotes. h/t #bad_coder.
To add two dashes, add the following:
.. include:: <isotech.txt>
|minus|\ |minus|\ region
Note the backward-slash and the space. This avoids having a space between the minus signs and the name of the parameter.
You only need to include isotech.txt once per page.
With this solution, you can keep the extension smartypants and write two dashes in every part of the text you need. Not just in option lists or literals.
As commented by #mzjn, the best way to address the original submitter's need is to use Option Lists.
The format is simple: a sequence of lines that start with -, --, + or /, followed by the actual option, (at least) two spaces and then the option's description:
-l long listing
-r reversed sorting
-t sort by time
--all do not ignore entries starting with .
The number of spaces between option and description may vary by line, it just needs to be at least two, which allows for a clear presentation (as above) on the source, as well as on the generated document.
Option Lists have syntax for an option argument as well (just put an additional word or several words enclosed in <> before the two spaces); see the linked page for details.
The other answers on this page targeted the original submitter's question, this one addresses their actual need.