Tiny typographical error in install/uninstall docs

[simonw]

Added in:

• sqlite-utils install command #483

I don't know how to fix this in Sphinx: I'm getting this: https://sqlite-utils.datasette.io/en/latest/cli.html#cli-install

The insert –convert and query –functions options

But I want it to display insert --convert and not insert –convert there.

Here's the code:

sqlite-utils/docs/cli.rst

Line 2125 in 8524703

The :ref:`insert -\\-convert <cli_insert_convert>` and :ref:`query -\\-functions <cli_query_functions>` options can be provided with a Python script that imports additional modules from the ``sqlite-utils`` environment.

[simonw]

I tried the tips in https://stackoverflow.com/questions/15258831/how-to-handle-two-dashes-in-rest (not the settings change though, because I might want smart quotes elsewhere) and they didn't work.

Maybe I should disable smart quotes entirely?

I feel like there should be an escaping trick that works here though. I tried insert -\\-convert but it didn't help.

[chapmanjacobd]

this is likely what you are looking for: https://stackoverflow.com/a/51076749/697964

but yeah I would say just disable smart quotes

[simonw]

Based on the docs here I tried the following too: https://docutils.sourceforge.io/docs/user/smartquotes.html#description

• \--
• \\--
• \\-\\-
• \-\-

But none of them had the desired effect in this particular piece of markup:

the :ref:`insert \--convert <cli_insert_convert>` 

I think because this is text inside a :ref: block, not regular text.

Consider the following:

The \--convert and the :ref:`insert \--convert <cli_insert_convert>` and

It's rendered like this:

[tobych]

Disabling smart quotes entirely is probably the way. If you really want m-dashes or n-dashes you can just put them in the text. And the sort of people who use this library are likely to be normal, mentally stable individuals who would be more than happy to do wihout LaTeX-level typography if it means they can copy command options from documentation into their shell and not be confused for the next few minutes of their life.

[adrianrfreedman]

I had a look at this. Escaping cannot work here, and the settings change has a side effect.

I built the docs on main (56dd097, Sphinx 9.1.0) with four variants in the :ref: text:

:ref:`insert \--convert <cli_insert_convert>`
:ref:`insert \-\-convert <cli_insert_convert>`
:ref:`insert -\-convert <cli_insert_convert>`
:ref:`insert --convert <cli_insert_convert>`

All four render as insert –convert. Role content is unescaped before the smartquotes transform runs, so the backslashes are already gone by the time smartquotes sees --. That applies to the -\\- currently in cli.rst too, which is why it looks like the escape is being ignored.

Disabling dashes globally does fix it, but there is a cost. smartquotes_action = "qe" in conf.py turns 275 autodoc parameter separators from – into -- across reference.html. Sphinx emits those separators as a literal -- and relies on smartquotes to render the en-dash, so the same switch that saves the options loses the separators. smartquotes = False does the same thing.

The only thing that works is moving the option out of the link text into inline literal markup, which smartquotes skips:

the ``--convert`` option to :ref:`insert <cli_insert_convert>`

#737 already does this for the install section, so that one looks good to merge.

The same bug is in python-api.rst in six more places, all on "In the CLI:" lines, and none of the open PRs cover them:

• 188 sqlite-utils --attach
• 1028 sqlite-utils insert --not-null and --default
• 1191 sqlite-utils insert --replace
• 1660 sqlite-utils insert --alter
• 3363 sqlite-utils query --functions
• 3498 sqlite-utils create-database --init-spatialite

I have the fix for those six built and verified locally, clean -W build with the curly quotes and autodoc separators intact. Happy to open a PR for them if that's useful.