DOC: fix slashes in read_csv line_terminator/sep kwargs descriptions

[shawnheide]

• closes Too many backslashes stripped in documentation generation #13738
• tests added / passed
• passes git diff upstream/master | flake8 --diff
• whatsnew entry

Added additional '' characters in order to produce the correct format in the documentation.

[jorisvandenbossche]

@shawnheide Could you try if using raw strings works as well? Because that way it would maybe be possible to have it look good in both the plain text docstring as the online html one.

[shawnheide]

@jorisvandenbossche I hadn't thought about the docstrings before, still learning I guess. It looks like the build failed under 2.7 for some reason as well. I tried with raw docstrings and the Sphinx still converted them.

My last attempt was to use the raw docstrings and enclose the special characters ("/s+", etc.) in double back ticks, which keeps Sphinx from interpreting them. This works for the docs, but then the docstrings show the back ticks (see attached images). I searched the codebase for other examples of special characters in both the docstrings and documentation but couldn't find any. Anyone have any other ideas?

Docs:

Docstring:

[jorisvandenbossche]

And when using raw string, but without the backticks, sphinx does still interprete the backslash?
I thought it wouldn't, but if that is the case, I think this is the best solution possible (it looks good in html, and better in the docstring compared to the double backslashes

The travis failure is because we have a linter for one of the 2.7 builds. If you look at the log of the failing build, down below, there is the output of the linter:

pandas/io/parsers.py:282:80: E501 line too long (80 > 79 characters)

[shawnheide]

Yes, with raw string it still interprets backslash characters, so the docs look the same as they currently do now. I found the warning box on this page helpful in understanding what's going on with Sphinx.

Thanks for explaining the build failure. I looked at the details, but must have missed seeing that explanation. I'll make sure my next commit keeps the code at less than 80 characters long.

Just to clarify, you're saying to use the version I posted images for with the raw docstrings and the backticks correct?

[jorisvandenbossche]

Just to clarify, you're saying to use the version I posted images for with the raw docstrings and the backticks correct?

Yes, those look good!

Yes, with raw string it still interprets backslash characters, so the docs look the same as they currently do now. I found the warning box on this page helpful in understanding what's going on with Sphinx.

My interpretation is that the raw string ensures that sphinx sees the backslash, but that sphinx also uses the backslash itself to escape characters it uses (eg * for bold), so in this way to show a backslash in sphinx, you still need two of them in the raw string (or four in the python string), or put it in a literal code block, like you proposed now.

[codecov-io]

Current coverage is 85.31% (diff: 100%)

Merging #13761 into master will decrease coverage by <.01%

@@             master     #13761   diff @@
==========================================
  Files           141        141          
  Lines         50679      50679          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
- Hits          43240      43239     -1   
- Misses         7439       7440     +1   
  Partials          0          0          

Powered by Codecov. Last update 474fd05...bc320dd

[jorisvandenbossche]

@shawnheide Thanks a lot!
Really nice to have some doc contributions!