Struggling with target headers in sphinx build + myst

Questions about Python Packaging & Code
1

Hey y’all. HOping someone can help me with an ongoing battle with myst target headers in our docs!

I have a page:
documentation/package-documentation-best-practices.md
And it has the header below:

(docstring_best_practice)=
### Best - a docstring with example use of the function

i have a link on : documentation/python-package-documentation-tools.md

[In the package documentation page we provided some examples of good, better, best docstring formats](/documentation/package-documentation-best-practices.html#best-a-docstring-with-example-use-of-the-function)

my markdown link to that target doesn’t work! i’ve tried multiple things including

package-documentation-best-practices#docstring_best_practice
package-documentation-best-practices.html#docstring_best_practice

etc

and sphinx build will not build the link meaning it can’t find the link. How do i correctly create a link to a target header using myst?
extensions here:

extensions = [
    "myst_nb",
    "sphinx_design",
    "sphinx.ext.intersphinx",
    "sphinx_sitemap",
    "sphinxext.opengraph",
    "sphinx_copybutton",
]

Full guide here: GitHub - pyOpenSci/python-package-guide: A guide to scientific python package recommendations curated by pyOpenSci

many thanks for any help y’all!

2

Hi @lwasser I think you want to use the inline role {ref} which maps directly to the rst :ref: role.

So you would write

{ref}`In the package documentation page we provided some examples of good, better, best docstring formats <docstring_best_practice>`

Notice that to get alternate text the same you do in your markdown snippet, you need to write the target for the header you’re referencing verbatim in the angle brackets, with the alternate text before it. If instead you just wrote

{ref}`docstring_best_practice`

the MyST parser would fill in the actual text of the header “Best - a docstring with example use of the function” the same way that Sphinx does when you use a :ref:.

I just realized, re-reading that section, they do say you can use markdown syntax like you do above, but in that case I think you still would write just the target header, like this

[In the package documentation page we provided some examples of good, better, best docstring formats](docstring_best_practice)
1 Like
3

OK! i think i better understand. i’ll try again and will look at the parser docs for more info!! let’s see how this goes!

many thanks!

4

Yes you’ve got it, you could say a target is a global element.

It’s one of those Sphinx abstractions that’s trying to let you reference things anywhere in the docs without having to do stuff like manually write a whole url with an anchor.

You can use a markdown link to reference a target above a header, but you don’t write it like an anchor, you write the target itself. Maybe the explanation in the MyST parser docs gives a little more detail than what you’re looking at in the Jupyter book docs?

Sorry, I thought I had included that link in my first reply

1 Like
5

ok this now is working. SO the fix is

[text here](anchor-text-only)

Rather than [text-here](a-link/a-page#anchor-text)
But weirdly it is actually on the back end creating a normal anchor but it must just figure out how to create the full link when it builds!

1 Like