Option defaults with escape characters don't render correctly

[morcef]

Hi,

I am using a Typer CLI app, and making use of typer_click_object to generate my documentation. However I see that a default value that is a Path will render incorrectly in the documentation:

This is rendered by the following code:

@app.command()
def cli(some_path: Path = Option(Path("/this/is/a/path"))):
    """Bad default for --some-path."""

    pass

typer_click_object = get_command(app)

And the following rst:

.. click:: some_prog:typer_click_object
   :prog: some_prog
   :nested: full

I must admit I do not know where this issue lies, or where I can try to figure it out, so this is my first attempt.

[stephenfin]

I haven't played with Typer so it's not really supported. Can you provide a minimal reproduction repo (ideally including a setup.py or requirements.txt file) so I or someone else can look at this?

[morcef]

Hi @stephenfin , Sorry for the delay, but I have now set up https://github.com/morcef/sphinx-click-111 as a minimal reproduction. I am unfortunately stuck on Python36, but I have created two branches in my repo, one for Python310 (main) and the latest versions of all dependencies, and one for Python36 (python36) with the highest compatible versions of the dependencies. Both of them seem to give the same output.

In addition to the bad path representation, I can also see that if I make a similar Click app, the default value isn't even displayed in the docs. Is there something I am doing wrong?

These are my output docs: Typer:

Click:

[stephenfin]

I don't think this is something I can fix. I'm not sure what's going on here, but it looks like something to do with your environment. This is what I see locally:

To get to this, I cloned the reproducer repo locally and removed the theme configurations since it wasn't necessary:

❯ git diff
diff --git docs/conf.py docs/conf.py
index 99063a0..c0eb07c 100644
--- docs/conf.py
+++ docs/conf.py
@@ -29,34 +29,15 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     "sphinx_click",
-    "sphinx_rtd_dark_mode",
 ]

 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

-html_theme = 'sphinx-rtd-theme'
-html_static_path = ['_static']
-
-html_theme_options = {
-    "logo_only": False,
-    "display_version": True,
-    "prev_next_buttons_location": "bottom",
-    "style_external_links": False,
-    "style_nav_header_background": "black",
-    # Toc options
-    "collapse_navigation": False,
-    "sticky_navigation": True,
-    "navigation_depth": 5,
-    "includehidden": True,
-    "titles_only": False,
-}
-
 # General autodoc settings
 autodoc_default_options = {
     "members": True,

I then installed dependencies:

❯ virtualenv venv
❯ source venv/bin/activate
❯ pip install .
❯ pip install sphinx-click sphinx_autodoc_typehints
❯ make -C docs/ html
❯ python -m http.server -d docs/_build/html

Out of curiosity, what happens if you execute the following in your local environment?

>>> import pathlib
>>> str(pathlib.Path('/this/is/a/path'))

I see

'/this/is/a/path'

I wonder if you see the same.

Closing this as working as expected.

[morcef]

Thank you @stephenfin for looking into this. It is a curiosity.

>>> import pathlib
>>> pathlib.Path("/this/is/a/path")
WindowsPath('/this/is/a/path')
>>> str(pathlib.Path("/this/is/a/path"))
'\\this\\is\\a\\path'

As you can see, I am currently on a Windows system. I don't believe that should be an issue?

[stephenfin]

Ah, a curiosity indeed :slightly_smiling_face: If you include '\this\is\a\path' in a a rST document, it renders as thisisapath because the backslashes are interpreted as escapes. We'd need to render the default values as literals (i.e. code) to avoid this. I need to think about the implications of this.