I'm considering to move my documentation from Doxygen to Sphinx and looking for an alternative for Doxygen alias.
In Doxygen I have an alias that replaces complex command like a table to a more readable format like this (this just an examples and i have more complex and nested ones) :
table_row2{2}=<tr><td align= center>\1</td><td align= center>\2</td></tr>
or
limited_res{1}=The number of supported \1 depends on the specific platform. See the \ref appendixes section"
It can be used in the documentation like this:
...
table_h2{ Resource Name, Value }
table_row2{ MAC Entries , 256}
table_row2{ Ingress Flow , \limited_res { Ingress Flow } }
...
The closest thing I found in Sphinx is substitutions, but I have trouble to get it to work even for simple command substitutions one like below:
.. |H1| replace:: `*****************************************************`
My section
|H1|
H1 either does not compile or just print the '*...*'.
I'm not sure if this is a syntax problem or just can't be done. I trying to avoid remembering which of the */ +/ -/ = means what and name it by the level of the nesting. My memory is not very good this days :)
And the more important problem: substitutions does not seem to accept parameters which I found essential.
Another option I can think about is to write extensions like this, but I hope for a more simple method.
To get the asterisks to appear below "My section", you need to have at least one blank line separating "My section" from "|H1|". White space in Sphinx/docutils has meaning, and the separated content gets interpreted as two paragraphs instead of inline text.
.. |H1| replace:: `*****************************************************`
My section
|H1|
To display the backticks, escape them with the backslash character \.
.. |H1| replace:: \`*****************************************************\`
My section
|H1|
In case you want to insert raw, you may use the raw directive.
EDIT
This creates a section.
My section
==========
A blank line between two paragraphs will generate paragraphs, as noted above.
Related
My company uses FreeBSD, and therefore FreeBSD's flavor of make.
A few of our in-house ports include something like this (where BRANCH is something that came from an SVN URL, either 'trunk' or a branch name like 'branches/1.2.3').
PORTVERSION= ${BRANCH:C,^branches/,,}
The Variable modifiers section of make(1) documents the :C colon-c modifier as
:C/pattern/replacement/[1gW]
Am I looking at the right documentation? ^branches/ looks like a regex pattern to me, but it looks like the actual code uses , instead of / as a separator. Did I skip documentation explaining that?
The documentation says:
:C/pattern/replacement/[1gW]
The :C modifier is just like the :S modifier except that the old and new strings, instead of being simple strings, are an extended regular expression (see regex(3)) string pattern and an ed(1)-style string replacement.
and in :S:
Any character may be used as a delimiter for the parts of the modifier string.
As #MadScientist pointed out, it's quite common to use a different delimiter, especially when / is a part of pattern or replacement string, like in your case. Otherwise it would require escaping and would look like ${BRANCH:C/^branches\///} which seems less readable.
I have created a custom directive for a documentation project of mine which is built using Sphinx and reStructuredText. The directive is used like this:
.. xpath-try:: //xpath[#expression="here"]
This will render the XPath expression as a simple code block, but with the addition of a link that the user can click to execute the expression against a sample XML document and view the matches (example link, example rendered page).
My directive specifies that it does not have content, takes one mandatory argument (the xpath expression) and recognises a couple of options:
class XPathTryDirective(Directive):
has_content = False
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = True
option_spec = {
'filename': directives.unchanged,
'ns_args': directives.unchanged,
}
def run(self):
xpath_expr = self.arguments[0]
node = xpath_try(xpath_expr, xpath_expr)
...
return [node]
Everything seems to be working exactly as intended except that if the XPath expression contains a * then the syntax highlighting in my editor (gVim) gets really messed up. If I escape the * with a backslash, then that makes my editor happy, but the backslash comes through in the output.
My questions are:
Are special characters in an argument to a directive supposed to be escaped?
If so, does the directive API provide a way to get the unescaped version?
Or is it working fine and the only problem is my editor is failing to highlight things correctly?
It may seem like a minor concern but as I'm a novice at rst, I find the highlighting to be very helpful.
Are special characters in an argument to a directive supposed to be escaped?
No, I think that there is no additional processing performed on arguments of rst directives. Which matches your observation: whatever you specify as an argument of the directive, you are able to get directly via self.arguments[0].
Or is it working fine and the only problem is my editor is failing to highlight things correctly?
Yes, this seems to be the case. Character * is used for emphasis/italics in rst and it gets more attention during syntax highlighting for some reason.
This means that the solution here would be to tweak or fix vim syntax file for restructuredtext.
How can I make a part of a word bold in reStructuredText?
Here is an example of what I need: ".rst stands for restructured text."
I was surprised that you could not simply write
.rst stands for **r**e**s**tructured **t**ext.
but the reStructuredText specification indeed states that inline markup must be followed by white-space or one of - . , : ; ! ? \ / ' " ) ] } or >, so the above string of reStructuredText is not valid. However, only a minor change is required to get valid character markup with backslash escapes. Changing the above to
.rst stands for **r**\ e\ **s**\ tructured **t**\ ext.
works fine. To see this in action try the online reST to HTML converter.
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.
I'm having problems about a regexp.
I'm trying to implement a regex to select just the tab indent blocks, but i cant find a way of make it work:
Example:
INDENT(1)
INDENT(2)
CONTENT(a)
CONTENT(b)
INDENT(3)
CONTENT(c)
So I need blocks like:
INDENT(2)
CONTENT(a)
CONTENT(b)
AND
INDENT(3)
CONTENT(c)
How I can do this?
really tks, its almost that, here is my original need:
table
tr
td
"joao"
"joao"
td
"marcos"
I need separated "td" blocks, could i adapt your example to that?
It depends on exactly what you are trying to do, but maybe something like this:
^(\t+)(\S.*)\n(?:\1\t.*\n)*
Working example: http://www.rubular.com/r/qj3WSWK9JR
The pattern searches for:
^(\t+)(\S.*)\n - a line that begins with a tab (I've also captured the first line in a group, just to see the effect), followed by
(?:\1\t.*\n)* - lines with more tabs.
Similarly, you can use ^( +)(\S.*)\n(?:\1 .*\n)* for spaces (example). Mixing spaces and tabs may be a little problematic though.
For the updated question, consider using ^(\t{2,})(\S.*)\n(?:\1\t.*\n)*, for at least 2 tabs at the beginning of the line.
You could use the following regex to get the groups...
[^\s]*.*\r\n(?:\s+.*\r*\n*)*
this requires that your lines not begin with white space for the beginning of the blocks.