[petsc-dev] Still unable to provide link from manual page into users manual after Sphinx

[Lawrence Mitchell]

On Sun, 28 Aug 2022 at 18:40, Barry Smith <bsmith at petsc.dev> wrote:
>
>
>
> On Aug 28, 2022, at 8:10 AM, Lawrence Mitchell <wence at gmx.li> wrote:
>
> On Thu, 25 Aug 2022 at 13:37, Barry Smith <bsmith at petsc.dev> wrote:
>
>
>
>  That would be great, thanks. Perhaps I am just not passing the label in the correct format in the .md file, I tried everything I could think of (and everything google suggested), and it either a) left my text untouched, meaning it didn't realize what I was providing was supposed to be a label or b) it complained that the label I provided did not exist.
>
>
> So I've had a go and can make the following work:
>
>
>   Thanks for checking on this. I am a bit confused.
>
>
> If I edit one of the manual pages (e.g.
> doc/_build_classic/docs/manualpages/Mat/MATAIJCRL.md):
>
> This works for me to create a link to the explicitly labelled section
> in the main manpages
>
> [creating matrices](sec_matcreate)
>
>
> What do you mean by "to the explicitly labeled section in the main manpages"?

> Do you mean if one has an "explicitly labeled section" in the users manual like
>
> .. _sec_matcreate:
>
> Then I can use [creating matrices](sec_matcreate) inside a manual page and it does things properly? (I thought I tried this and it did not work, I'll try again).

Yes, exactly.

> Does the "explicitly labeled section" have to be only in the users manual or can it be anywhere on the Sphinx website?

No, it can be anywhere on the sphinx website.
E.g. all of these work:

{any}`sec_matcreate` or [](sec_matcreate)

{any}`../Vec/VecCreate` or [](../Vec/VecCreate) or
[](/docs/manualpages/Vec/VecCreate)

{any}`/overview/nutshell` or [](/overview/nutshell)

If you provide something without some path-like syntax, then it seems
like myst/sphinx will look for it as a label. Otherwise you can
provide absolute or relative paths with / being the root of the
website, so [](/index) gets you to the front page.

This whole system appears to be built by someone who hates
cross-linking and doesn't think it should be easy to do in a manual
:(.

Lawrence