WARNING reference target not found, even though reference exists

Describe the bug

context After upgrading MyST-Parser to the latest version, we’re seeing these warnings while building our docs with Sphinx:

/home/runner/work/tango/tango/docs/source/CONTRIBUTING.md:154: WARNING: 'myst' reference target not found: #writing-docstrings
/home/runner/work/tango/tango/docs/source/CONTRIBUTING.md:179: WARNING: 'myst' reference target not found: #making-a-pull-request

MyST-Parser is complaining about internal header links in this file, such as on this line, even though those links clearly exists.

expectation No warnings.

problem This is causing a problem in our docs build, since we treat warnings as errors. We could silence these specific warnings, but I’d rather not do that since it could cause us to miss true positives in the future.

Reproduce the bug

git clone https://github.com/allenai/tango.git
cd tango
git checkout dependabot/pip/myst-parser-0.17.0
pip install -e '.[dev,all]'
make docs

List your environment

Python 3.9

absl-py==0.15.0
-e git+ssh://[e-mail]/allenai/tango.git@f46379b9fac6cb77a2a5f8ef34a1fb208203d587#egg=ai2_tango
aiohttp==3.7.4.post0
alabaster==0.7.12
appnope==0.1.2
async-timeout==3.0.1
attrs==21.2.0
Babel==2.9.1
backcall==0.2.0
base58==2.1.0
beautifulsoup4==4.10.0
black==21.12b0
bleach==4.1.0
boto3==1.18.47
botocore==1.21.47
cached-path==1.0.2
cachetools==4.2.2
certifi==2021.5.30
chardet==4.0.0
charset-normalizer==2.0.6
click==8.0.3
click-help-colors==0.9.1
codecov==2.1.12
colorama==0.4.4
configparser==5.0.2
coverage==5.5
datasets==1.18.1
decorator==5.1.0
deepspeed==0.5.5
dill==0.3.4
distlib==0.3.4
docker-pycreds==0.4.0
docopt==0.6.2
docutils==0.17.1
fairscale==0.4.5
filelock==3.4.0
flake8==3.9.2
flaky==3.7.0
Flask==2.0.2
fsspec==2021.9.0
furo==2022.1.2
future==0.18.2
gitdb==4.0.7
GitPython==3.1.24
glob2==0.7
google-api-core==2.0.1
google-auth==2.1.0
google-auth-oauthlib==0.4.6
google-cloud-core==2.0.0
google-cloud-storage==1.42.2
google-crc32c==1.2.0
google-resumable-media==2.0.3
googleapis-common-protos==1.53.0
GPUtil==1.4.0
greenlet==1.1.1
grip==4.5.2
grpcio==1.41.1
huggingface-hub==0.2.1
idna==3.2
imagesize==1.2.0
importlib-metadata==4.8.1
iniconfig==1.1.1
ipython==7.28.0
isort==5.10.1
itsdangerous==2.0.1
jedi==0.18.0
Jinja2==3.0.1
jmespath==0.10.0
joblib==1.1.0
jsonnet==0.17.0
keyring==23.2.1
livereload==2.6.3
m2r==0.2.1
Markdown==3.3.4
markdown-it-py==1.1.0
MarkupSafe==2.0.1
matplotlib-inline==0.1.3
mccabe==0.6.1
mdit-py-plugins==0.3.0
mistune==0.8.4
more-itertools==8.10.0
msgpack==0.5.6
multidict==5.1.0
multiprocess==0.70.12.2
mypy==0.931
mypy-extensions==0.4.3
myst-parser==0.17.0
neovim==0.2.6
ninja==1.10.2.2
nltk==3.6.7
numpy==1.21.2
oauthlib==3.1.1
overrides==6.1.0
packaging==21.0
pandas==1.3.3
parso==0.8.2
path-and-address==2.0.1
pathspec==0.9.0
pathtools==0.1.2
petname==2.6
pexpect==4.8.0
pickleshare==0.7.5
Pillow==9.0.0
pkginfo==1.7.1
platformdirs==2.3.0
pluggy==1.0.0
promise==2.3
prompt-toolkit==3.0.20
protobuf==3.18.0
psutil==5.8.0
ptyprocess==0.7.0
py==1.10.0
pyarrow==5.0.0
pyasn1==0.4.8
pyasn1-modules==0.2.8
pycodestyle==2.7.0
pyDeprecate==0.3.1
pydocstyle==6.1.1
pyflakes==2.3.1
Pygments==2.10.0
pyparsing==2.4.7
pytest==6.2.5
pytest-cov==2.12.1
pytest-sphinx==0.3.1
python-dateutil==2.8.2
pytorch-lightning==1.5.9
pytz==2021.1
PyYAML==5.4.1
readme-renderer==29.0
regex==2021.8.28
requests==2.26.0
requests-oauthlib==1.3.0
requests-toolbelt==0.9.1
rfc3986==1.5.0
rouge-score==0.0.4
rsa==4.7.2
s3transfer==0.5.0
sacremoses==0.0.46
sentencepiece==0.1.96
sentry-sdk==1.4.3
shortuuid==1.0.1
six==1.16.0
smmap==4.0.0
snowballstemmer==2.1.0
soupsieve==2.2.1
Sphinx==4.4.0
sphinx-autobuild==2021.3.14
sphinx-copybutton==0.5.0
sphinx-design==0.0.13
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
sqlitedict==1.7.0
subprocess32==3.5.4
tensorboard==2.7.0
tensorboard-data-server==0.6.1
tensorboard-plugin-wit==1.8.0
tensorboardX==1.8
termcolor==1.1.0
tokenizers==0.10.3
toml==0.10.2
tomli==1.2.1
torch==1.10.1
torchaudio==0.10.1
torchmetrics==0.6.0
torchvision==0.11.2
tornado==6.1
tqdm==4.62.3
traitlets==5.1.0
transformers==4.15.0
twine==3.4.2
types-PyYAML==6.0.0
types-setuptools==57.4.2
typing-extensions==3.10.0.2
typing-utils==0.1.0
urllib3==1.26.7
virtualenv==20.13.0
wandb==0.12.4
wcwidth==0.2.5
webencodings==0.5.1
Werkzeug==2.0.2
xxhash==2.0.2
yarl==1.6.3
yaspin==2.1.0
zipp==3.5.0

[chrisjsewell]

Heya, yes this is expected behaviour. Before, it was treating these links starting # as an external link, but now you should explicitly use: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=anchor#auto-generated-header-anchors

Can you give that a go and let me know if it works, e.g. adding myst_heading_anchors = 1

If so I’ll update the changelog, to specifically mention this change

[eyllanesc]

@chrisjsewell @epwalsh

I was testing that bug and check that with myst_heading_anchors = 3 it works (with values from 3 to 7 too).

I think that by default myst_heading_anchors should have the highest possible value or allow to use -1 to indicate it since for example for this case with 2 it does not work since one of the references is h3 and use the myst-anchors tool I think it annoying, you should only call it if placing a small myst_heading_anchors optimizes some task (if it does).