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

[Barry Smith]

  Lawrence,

   Thanks, I'm going to go with the  [optional text](sec_matcreate) syntax

> On Aug 28, 2022, at 2:42 PM, Lawrence Mitchell <wence at gmx.li> wrote:
> 
> 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