executablebooks / MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx
https://myst-parser.readthedocs.io
MIT License
759 stars 196 forks source link

`cross-references.md`: Handling `name`s with spaces #991

Open goekce opened 3 weeks ago

goekce commented 3 weeks ago

Describe the gap in the current documentation

I followed https://github.com/executablebooks/MyST-Parser/blob/59b5386f92f54241d0036e0726e93b4086970e03/docs/syntax/cross-referencing.md?plain=1#L286

However, I spent significant time figuring out how to link the following name with spaces:

$ myst-inv https://ipywidgets.readthedocs.io/en/latest -n "examples/Using Interact"

name: Jupyter Widgets
version: '8.1'
base_url: https://ipywidgets.readthedocs.io/en/latest
objects:
  std:
    doc:
      examples/Using Interact:
        loc: examples/Using%20Interact.html
        text: Using Interact

For example the following did not work:

<inv:ipywidgets:std:doc#examples/Using Interact>
<inv:ipywidgets:std:doc#examples/"Using Interact">

It turns out one has to encode the spaces:

<inv:ipywidgets:std:doc#examples/Using%20Interact>

The documentation above does not include info about how to encode spaces.

Describe the solution you'd like

I would like to add a paragraph about encoding spaces. What do you think?