Documentation - Upgrade Myst Parser #11194
Conversation
Manage this branch in SquashTest this branch here: https://nxpy123update11178-update-myst-dzbh3.squash.io |
lb-
added
Documentation
status:Needs Review
dependencies
|
When I run the docs build locally I get some loud warnings, all relating to the Django cross-reference, maybe there is a different config structure needed here. My guess is that this would be a config issue https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html Or maybe these warnings always existed and are now not suppressed https://myst-parser.readthedocs.io/en/latest/configuration.html#build-warnings It looks like it's building correctly though. 
|
|
I think it might be because the pages no longer exist in the Django site? |
|
I do not think that's it, for example Django topics signals exists https://docs.djangoproject.com/en/4.1/topics/signals/ My guess is that MyST is expecting to read it's own config for these Django ones but the parsing / processing of those links happens in RTD (Read The Docs). see Sorry I do not know much more about how this works but hopefully that helps you debug. |
There was a problem hiding this comment.
You might have to update those links to use the inv: syntax and possibly update the configuration as well:
https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#cross-project-intersphinx-links
|
I usually find that I have to run Thanks for keeping at this. |
|
Thanks for that info! The warnings come up when I do |
|
Some of the warnings are because there's a # infront of the URL in the html built by Sphinx. For example, this warning: This is the line that gives the warning in the html file built by sphinx: The URL works when you remove the # in front of it. Even for django, it only places a # infront of the url it generates instead of considering it as an intersphinx mapping: |
|
External links require |
|
Great digging @NXPY123 that seems like it could be a path in the right direction. We would want to probably add Let's not add the |
|
Based on the docs: 
None of the URI's aren't prefixed by inv and also I'm not sure if the key,domain,type and name are according to the inventory file. That might be the issue. |
|
The Django inv file is in this format: So to generate url to |
|
@NXPY123 nice find. Can you maybe update one or two pages on this PR with that format. We can do some testing. If that works and others on the core team are happy with that global change, I think we go for it. Also. Maybe do a search around GitHub and see if any other documentation sites using MyST have that. Just a reference that we're not doing something wrong here. |
|
@NXPY123 also please test a file with an RST embedded code, so we can check it works in that also. |
The following lines: are being rendered as: <li><p><a class="reference external" href="https://docs.djangoproject.com/en/4.2/intro/tutorial02/#creating-models" title="(in Django v4.2)"><span class="xref std std-ref">Creating models</span></a></p></li>
<li><p><a class="reference external" href="https://docs.djangoproject.com/en/4.2/topics/db/models/" title="(in Django v4.2)"><span class="xref std std-doc">Model syntax</span></a></p></li>in the html file |
|
In numpy docs the following lines are present: In https://pandas.pydata.org/pandas-docs/stable/objects.inv, |
There was a problem hiding this comment.
@NXPY123 thank you! This is looking great.
I think we need to make a few more tweaks but you have the go ahead to update all refs (based on the notes below).
- Keep the intersphinx mapping to the stable urls, not the 4.2 urls.
- After my 3rd reading of the docs section on intersphinx mapping I think we need to make one more tweak to the URL refs. https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html#cross-project-intersphinx-links (see code below)
Instead of (django:ref/models/fields) we should be using the (inv:django#ref/models/fields) note the usage of inv:django. This says use the inv schema (as in a custom URL resolover) and then use the key 'django'.
Finally the #name format means that the name it will search for will be ref/models/fields in this case.
From the docs...
you can then reference inventory objects by prefixing the inv schema to the destination URI: inv:key:domain:type#name.
key, domain and type are optional, e.g. for inv:#name, all inventories, domains and types will be searched, with a warning emitted if multiple matches are found.
Additionally, * is a wildcard which matches zero or characters, e.g. inv::std:doc#a will match all std:doc objects in all inventories, with a name beginning with a. Note, to match to a literal * use *.
|
@NXPY123 I have an update coming to this branch with the reference changes as this ended up being pretty close. I will also push an update to the documentation guidelines with a basic example of these new formats. Unfortunately it appears that there may be differences in the rst vs markdown format but most usage is MD format so it should be ok. |
lb-
force-pushed
the
update/11178-update-myst-parser
branch
from
142f262
to
fca7210
Compare
lb-
force-pushed
the
update/11178-update-myst-parser
branch
from
fca7210
to
9c6f582
Compare
There was a problem hiding this comment.
Thank you @NXPY123 this is a great win!
Hopefully MyST will add some improvements to the way intersphinx refs work but overall it's great to have this updated and aligned with the latest conventions.
Thanks also for pushing through and learning how to use this docs setup really well.
Partially reverts commit 7fa335c (fixing some issues with the URL updates)
Partially reverts commit 7fa335c (fixing some issues with the URL updates)
Resolves #11178. Myst Parser can be updated to 2.0.0, but support for Python 3.7 will be lost.
Please check the following:
make lintfrom the Wagtail root.