executablebooks / MyST-Parser

An extended commonmark compliant parser, with bridges to docutils/sphinx
https://myst-parser.readthedocs.io
MIT License
754 stars 197 forks source link

links to documentation generated with sphinx-apidoc no longer work #574

Open jclerman opened 2 years ago

jclerman commented 2 years ago

Describe the bug

context When I

  1. use sphinx-apidoc to create API documents for a Python project, e.g.:
    sphinx-apidoc -f --module-first -o source/ my_python_package_dir
  2. place links to anchors within those API documents, e.g. within my_manual_page.md, place:
    [MyClass](../source/my_python_package.html#my_python_package.my_module.MyClass)

expectation I expected documentation to be built correctly, no errors, and for the generated HTML file from my_manual_page.md to have a link to the documentation for MyClass.

That worked fine through version 0.16.x of myst-parser

bug But instead I get a "reference target not found" warning, like:

Warning, treated as error:
my_manual_page.md:123:'myst' reference target not found: ../source/my_python_package.html#my_python_package.my_module.MyClass

problem This is a problem since there no longer seems to be any way to include links to sphinx-apidoc generated documentation. Note that this seems to occur even if anchors to a specific module/class are not included in the link.

I imagine that this might be related to the breaking changes announced for v0.17.0, but the fixes recommended in the breaking-change announcement did not work for me; the only solution was to roll back to v0.16.x. The closest thing to a fix was to set myst_all_links_external = True, but then that breaks links to other non-html local documentation files (e.g. *.md files).

Reproduce the bug

see above under context

List your environment

MacOS 12.4
python 3.8.7
sphinx 4.5.0
myst-parser 0.17.2 (works fine with 0.16.1)
welcome[bot] commented 2 years ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada: