Cross-referencing `envvar`

[paw-lu]

.. click:: nbpreview.__main__:typer_click_object
   :prog: nbpreview / nbp
   :nested: full

:program:`nbpreview / nbp`

:option:`--plain`

:option:`--decorated`

:option:`nbpreview / nbp --plain`

:envvar:`NBPREVIEW_PAGING`

Testing out the cross-referencing for this library. I can only get option to work correctly and generate a link. I think program is not expected to work, but why isn't envvar working? The environmental variables are listed on the page, but unlike the other elements, they don't seem to generate an anchor link (no ¶ symbol). Is this an upstream sphinx bug? Want to make sure that I'm using this correctly.

---

Thanks for sharing this work, it's been really useful!

[stephenfin]

Testing out the cross-referencing for this library. I can only get option to work correctly and generate a link. I think program is not expected to work,

Unfortunately not, no.

but why isn't envvar working? The environmental variables are listed on the page, but unlike the other elements, they don't seem to generate an anchor link (no ¶ symbol). Is this an upstream sphinx bug? Want to make sure that I'm using this correctly.

Normally this would work, but we found that envvars were extremely likely to conflict. As a result, you need to use ref instead and reference it with {command_name}-{param_name}-{envvar}. In your example, this would probably look like:

:ref:`nbpreview-paging-NBPREVIEW_PAGING`

[stephenfin]

We should document this...

[paw-lu]

Thank you so much @stephenfin for both the explanation and documentation. Really appreciated!

[paw-lu]

@stephenfin this isn't working for me actually.

Usage2
======

.. click:: nbpreview.__main__:typer_click_object
   :prog: nbpreview
   :nested: full

:program:`nbpreview`

:option:`--paging`

:option:`nbpreview --paging`

:ref:`nbpreview-paging-NBPREVIEW_PAGING`

[paw-lu]

Update, explictly wrapping the reference in < > seems to generate the link, but I don't really know why to be honest.

Usage2
======

.. click:: nbpreview.__main__:typer_click_object
   :prog: nbpreview
   :nested: full

:program:`nbpreview`

:option:`--paging`

:option:`nbpreview --paging`

:ref:`foo <nbpreview-paging-NBPREVIEW_PAGING>`

But, while the link refers to the expected address—usage2.html#nbpreview-paging-nbpreview-paging, this link takes me nowhere.

[paw-lu]

But, while the link refers to the expected address—usage2.html#nbpreview-paging-nbpreview-paging, this link takes me nowhere.

Actually these links work as expected when clicked from another page.

Another page
============

.. This takes me to the envvar definition!
:ref:`foo <nbpreview-theme-NBPREVIEW_THEME>`

So something else is going on there. Mostly interested in why the < > is necessary right here, as it might help me solve other issues (https://github.com/executablebooks/MyST-Parser/issues/513).