<html><head><meta http-equiv="Content-Type" content="text/html; charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><br class=""><div><br class=""><blockquote type="cite" class=""><div class="">On Aug 28, 2022, at 8:10 AM, Lawrence Mitchell <<a href="mailto:wence@gmx.li" class="">wence@gmx.li</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="">On Thu, 25 Aug 2022 at 13:37, Barry Smith <<a href="mailto:bsmith@petsc.dev" class="">bsmith@petsc.dev</a>> wrote:<br class=""><blockquote type="cite" class=""><br class=""><br class=""> 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.<br class=""></blockquote><br class="">So I've had a go and can make the following work:<br class=""></div></div></blockquote><div><br class=""></div> Thanks for checking on this. I am a bit confused.</div><div><br class=""><blockquote type="cite" class=""><div class=""><div class=""><br class="">If I edit one of the manual pages (e.g.<br class="">doc/_build_classic/docs/manualpages/Mat/MATAIJCRL.md):<br class=""><br class="">This works for me to create a link to the explicitly labelled section<br class="">in the main manpages<br class=""><br class="">[creating matrices](sec_matcreate)<br class=""></div></div></blockquote><div><br class=""></div>What do you mean by "to the explicitly labeled section in the main manpages"? </div><div><br class=""></div><div>Do you mean if one has an "explicitly labeled section" in the users manual like </div><div><br class=""></div><div><div style="margin: 0px; font-stretch: normal; font-size: 14px; line-height: normal; font-family: Menlo; color: rgb(180, 36, 25);" class=""><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class="">.. _</span><span style="font-variant-ligatures: no-common-ligatures" class=""><b class="">sec_matcreate</b></span><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class="">:</span></div><div style="margin: 0px; font-stretch: normal; font-size: 14px; line-height: normal; font-family: Menlo; color: rgb(180, 36, 25);" class=""><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""><br class=""></span></div><div style="margin: 0px; font-stretch: normal; font-size: 14px; line-height: normal; font-family: Menlo;" class=""><span style="color: rgb(180, 36, 25);" class=""><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class="">Then I can use </span>[creating matrices](sec_matcreate)</span> inside a manual page and it does things properly? (I thought I tried this and it did not work, I'll try again).</div><div style="margin: 0px; font-stretch: normal; font-size: 14px; line-height: normal; font-family: Menlo;" class=""><br class=""></div><div style="margin: 0px; font-stretch: normal; font-size: 14px; line-height: normal; font-family: Menlo;" class="">Does the "explicitly labeled section" have to be only in the users manual or can it be anywhere on the Sphinx website? </div><div style="margin: 0px; font-stretch: normal; font-size: 14px; line-height: normal; font-family: Menlo;" class=""><br class=""></div><blockquote type="cite" class=""><div class=""><div class=""><br class="">To link to a page in the docs you can use<br class=""><br class="">[](/docs/manual/mat) (This uses the heading of the linked to page)<br class=""><br class="">Or<br class=""><br class="">[see also matrices](/docs/manual/mat)<br class=""><br class="">Critical is to provide an absolute path from the root (or else a<br class="">relative path [matrices](../../manual/mat))<br class=""></div></div></blockquote><div><br class=""></div>Can this be anywhere in the website or just in the docs directory? How come there is / in front of the docs in [](/docs/manual/mat) ? Does that / mean the root?</div><div><br class=""><blockquote type="cite" class=""><div class=""><div class=""><br class="">Of course, something you would think should be possible is to link to<br class="">the anchors that sphinx creates for every heading on every page, but<br class="">this appears to be impossible. The anchors are generated by the<br class="">backend unless you set some magic configuration option, and if you set<br class="">that, I can't convince sphinx to link from the manpages to an anchor<br class="">anyway.<br class=""><br class="">If you want to have relative links to the generated docs from the<br class="">markdown pages then set myst_all_links_external = True in conf.py and<br class="">then the link target will be pasted in literally so<br class="">[name](../../foo.html) turns into <a href="../../foo.html">name</a>.<br class="">If you do this, then the magic link searching doesn't work.<br class=""><br class="">Lawrence<br class=""><br class=""><blockquote type="cite" class=""><blockquote type="cite" class="">On Aug 25, 2022, at 5:56 AM, Lawrence Mitchell <<a href="mailto:wence@gmx.li" class="">wence@gmx.li</a>> wrote:<br class=""><br class="">Hi Barry,<br class=""><br class="">On Sun, 21 Aug 2022 at 20:56, Barry Smith <<a href="mailto:bsmith@petsc.dev" class="">bsmith@petsc.dev</a>> wrote:<br class=""><blockquote type="cite" class=""><br class=""><br class=""> To me, one of the best arguments to move to Sphinx was so that manual pages could have links directly into locations in the Users manual. Not possible in practice with a .pdf users manual.<br class=""><br class=""> With the manual in .rst and manual pages generated into .md this still appear to be impossible.<br class=""> 1) when Sphinx is processing .md pages it appears to not know about labels defined in .rst files so [matrix layout](sec_mat_something) doesn't work<br class=""> 2) Raw, cruder things like [matrix layout](../../manual/mat.html#matrix-and-vector-layouts-and-storage-locations) don't work because it doesn't realize what is inside is a raw URL. I am guessing it needs the http:// at the beginning to realize it is a HTPP url and not a markdown thing.<br class=""> 3) [matrix layout](<a href="https://petsc.org/main/docs/manual/mat/#matrix-and-vector-layouts-and-storage-locations" class="">https://petsc.org/main/docs/manual/mat/#matrix-and-vector-layouts-and-storage-locations</a>) works<br class=""><br class="">but hardwiring it this way is horrible. Could be release, could be (would be most of the time) a strange URL when running inside the CI. Is there a way to start with https::// but be a relative link?<br class="">figuring the anchor that Sphinx creates from a label (#matrix-and-vector-layouts-and-storage-locations) is super cumbersome.<br class=""><br class=""></blockquote><br class="">I am pretty sure something close to your option (1) _should_ work, I<br class="">will have a go at the weekend to see if I can figure things out. I<br class="">agree that any of the others are less good.<br class=""><br class=""><blockquote type="cite" class=""> Is the only good solution to somehow generate .rst files with sowing? How come that wasn't done initially and instead .md files were generated? It seems insanely bad to have this mixture of .md and .rst for a website.<br class=""></blockquote><br class="">This should not be necessary: rst and markdown are both frontend<br class="">formats to the parsed restructured text IR that sphinx uses (the<br class="">markdown version goes through one additional conversion step<br class="">internally, but that should not affect things here).<br class=""><br class="">Lawrence<br class=""></blockquote><br class=""></blockquote></div></div></blockquote></div><br class=""></body></html>