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.
Related
Sometimes I find myself editing a C source file which sees both use of tab as four spaces, and regular tab.
Is there any tool that attempts to parse the file and "normalize" this, i.e. convert all occurrences of four spaces to regular tab, or all occurrences of tab to four spaces, to keep it consistent?
I assume something like this can be done even with just a simple vim one-liner?
There's :retab and :retab! which can help, but there are caveats.
It's easier if you're using spaces for indentation, then just set 'expandtab' and execute :retab, then all your tabs will be converted to spaces at the appropriate tab stops (which default to 8.) That's easy and there are no traps in this method!
If you want to use 4 space indentation, then keep 'expandtab' enabled and set 'softtabstop' to 4. (Avoid modifying the 'tabstop' option, it should always stay at 8.)
If you want to do the inverse and convert to tabs instead, you could set 'noexpandtab' and then use :retab! (which will also look at sequences of spaces and try to convert them back to tabs.) The main problem with this approach is that it won't just consider indentation for conversion, but also sequences of spaces in the middle of lines, which can cause the operation to affect strings inside your code, which would be highly undesirable.
Perhaps a better approach for replacing spaces with tabs for indentation is to use the following substitute command:
:%s#^\s\+#\=repeat("\t", indent('.') / &tabstop).repeat(" ", indent('.') % &tabstop)#
Yeah it's a mouthful... It's matching whitespace at the beginning of the lines, then using the indent() function to find the total indentation (that function calculates indentation taking tab stops in consideration), then dividing that by the 'tabstop' to decide how many tabs and how many spaces a specific line needs.
If this command works for you, you might want to consider adding a mapping or :command for it, to keep it handy. For example:
command! -range=% Retab <line1>,<line2>s#^\s\+#\=repeat("\t", indent('.') / &tabstop).repeat(" ", indent('.') % &tabstop)
This also allows you to "Retab" a range of the file, including one you select with a visual selection.
Finally, one last alternative to :retab is that to ask Vim to "reformat" your code completely, using the = command, which will use the current 'indentexpr' or other indentation configurations such as 'cindent' to completely reindent the block. That typically respects your 'noexpandtab' and 'smarttabstop' options, so it use tabs and spaces for indentation consistently. The downside of this approach is that it will completely reformat your code, including changing indentation in places. The upside is that it typically has a semantic understanding of the language and will be able to take that in consideration when reindenting the code block.
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.
I'm redirecting output of an API call to file
however I always get the following characters surrounding the value I need
domainid='^[[39;49;00m^[[33;01m75307d12-e3f4-4a96-ac23-e2a9439f8299^[[39;49;00m'
Desired output
domainid='75307d12-e3f4-4a96-ac23-e2a9439f8299'
I really have no idea how to clean the output and make it look like the above.
Any suggestions will be highly appreciated.
Thank you
Those are ANSI control characters, or escape sequences, and they typically are used to add colors, underline, and so forth to your output.
First order of business is to check if your API command line tool supports a no-color mode. That would solve your problem at the source.
Barring that, try this Server Fault answer, which has a command to clear ANSI sequences out of a text file using sed.
You could remove the undesired characters by replacing the line with just the submatches you want to keep:
... | sed -r "s/(domainid=).*([0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}).*/\1'\2'/i"
Notepad++ obviously recognizes all comments as such. Is there a way to simply delete all?
Edit: Stat-R's bookmark method has helped greatly, not only for removing comments but for conditionally removing lines in general.
For a general file, first of all you need to know the comment operator of the language you are writing the file in. For example, in java script the comment operator is //.
For the following code...
In NP++, you need to
Mark the lines that contains '//'. Make sure the bookmark option is enabled.
Then, choose from NP++ menu Search>Bookmark>Remove Bookmarked lines
EDIT:
Another solution after #Chris Mirno 's suggestion is as follows:
Use regular expression. See the image below. It is self explanatory
To understand it better, refer to these
In the Find & Replace Dialog, put the following regex and adjust the search options as depicted.
/\*.*?\*/
Replace with: (empty)
Select Mode: Regular Expression AND .(dot) matches newline
This should remove all your C style comments spanned across lines.
Star-R and Chris Mirno Answer are also Correct and Good.
But For Line Comment:
//.*?(?=\r?$)
Explanation:
// will be the Starting Position
.*? Will be any character
(?=\r?$) will search to the end of the line (as it is required in line comment)
Note:
But Still check each of the line because for example if your code contains soap format like
//www.w3.org/2001/XMLSchema-instance\x2......");
it will capture this line because the starting is // and it goes to end of the line so watch out for this :)
Warning to all using Stat-R's solution:
This method will remove lines of code if formatted like this:
echo "hello"; //This comment will be detected
Following his method, the entire line will be removed.
Therefore make sure to go through and make these comments, their own line before doing this method.
I have had some luck running a macro for the above. Basically:
search for // (F3)
select to end of line (shift+end)
delete (delete)
Put // into the search dialog by just searching for it once. Then record the three steps in a macro, then play it back until EOF.
The first time I did it I had a problem, but then it worked, not sure what I did differently.
Anton Largiader's answer was the most reliable one, including complex inline comments.
However, it will leave many empty lines, including ones with empty characters (space, tabs...) so I would just add another step to make it almost perfect:
After running the macro, just do:
Edit > Line Operations > Remove Empty Lines
OR
Edit > Line Operations > Remove Empty Lines (Containing Blank Characters)
1st option is good if you wish to remove only really empty lines
2nd options will remove every empty line even containing space etc. so there will be no more actual spacing left between code blocks. 1st option might be the safest with some manual cleanup afterwards.
As someone suggested in another post, the simplest and most reliable is maybe to export the all text in .RTF format using Menu Plugin-->NppExport-->Export to RTF and then:
-Open the newly created file in Word
-Select any part of any comment
-On the top-right side of Word clic Select--> Select all texts with similar formatting
-Remove the selected comments all at once (del or cut if doesn't work)
To remove Powershell comments if someone find it handy:
Removing Comment in a Powershell using Notepad ++
To find just lines beginning with # (and not with # elsewhere in the line).
Notepad++ SEARCH Menu > Find
‘Mark‘ Tab – fill in as below.
Select ‘Mark All’ (clear all marks if used previously).
Regex ^[#}
enter image description here
SEARCH Menu > bookmark > Remove (or do anything on the list with
them)
Clear all marks to reset
You can select no comments just code by doing the following:
Regex ^[^#}
enter image description here
Enter ctrl+shift+K to remove comment
I have been looking at regular expressions to try and do this, but the most I can do is find the start of a line with ^, but not replace it.
I can then find the first characters on a line to replace, but can not do it in such a way with keeping it intact.
Unfortunately I don´t have access to a tool like cut since I am on a windows machine...so is there any way to do what I want with just regexp?
Use notepad++. It offers a way to record an sequence of actions which then can be repeated for all lines in the file.
Did you try replacing the regular expression ^ with the text you want to put at the start of each line? Also you should use the multiline option (also called m in some regex dialects) if you want ^ to match the start of every line in your input rather than just the first.
string s = "test test\ntest2 test2";
s = Regex.Replace(s, "^", "foo", RegexOptions.Multiline);
Console.WriteLine(s);
Result:
footest test
footest2 test2
I used to program on the mainframe and got used to SPF panels. I was thrilled to find a Windows version of the same editor at Command Technology. Makes problems like this drop-dead simple. You can use expressions to exclude or include lines, then apply transforms on just the excluded or included lines and do so inside of column boundaries. You can even take the contents of one set of lines and overlay the contents of another set of lines entirely or within column boundaries which makes it very easy to generate mass assignments of values to variables and similar tasks. I use Notepad++ for most stuff but keep a copy of SPFSE around for special-purpose editing like this. It's not cheap but once you figure out how to use it, it pays for itself in time saved.