-
Notifications
You must be signed in to change notification settings - Fork 3
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Internal cross-references MEP #10
Conversation
Thanks for submitting your first pull request! You are awesome! 🤗 |
This aligns the treatment of `[](#target)` style links for docutils with sphinx, such that they are linked to a heading slug. The core behaviour for sphinx is not changed, except that failed reference resolution now emits a `myst.xref_missing` warning (as opposed to a `std.ref` one), with a clearer warning message. Also on failure, the reference is still created, for people who wish to suppress the warning (see e.g. #677) This is another step towards jupyter-book/myst-enhancement-proposals#10
@chrisjsewell from a few comments you seemed to have strong opinions about the My thoughts on that are in the future we want a scheme to do more than what That being said, I think there is a lot of great work in the thinking behind links and we are already adopting it in our various parsers. What I propose:
If that sounds good, I can take a pass on cleaning up the final things in this PR and we can get it over to |
@chrisjsewell<https://github.com/chrisjsewell> from a few comments you seemed to have strong opinions about the myst url scheme - do you think that is the only thing holding this PR from moving into ACTIVE?
Heya, ok let me have a think and try to get this sorted by the weekend 😅
As you’ve seen I’ve heard be been trying to push this forward in some sense in myst-parser. Obviously the big pain in the backside there is trying to transition in a « back-compatible » way.
In terms of `myst` yeh hmm, I see your opinion, but it’s also not very « descriptive » of what it actually is 🤔
Chris
|
Nice. All I am proposing at this stage is that we kick the conversation about the For the rest of the MEP: are there outstanding parts you know/suspect are not backwards compatible? Perhaps we could take a similar approach. That is, make the MEP smaller and focus on shipping it and starting to turn these links on by default in various places! |
FWIW, I'll leave it to you two to decide the best path forward, but I agree that smaller and more tightly scoped proposals are easier to explain, discuss, and decide on. We can always make future progress in a new iteration. |
This PR moves myst-parser in the direction of jupyter-book/myst-enhancement-proposals#10, in a relatively back compatible manner, and in a way that supports both docutils and sphinx. It expands the capability of `[](#id)` to more than just linking to heading slugs, with the order of specificity being: 1. If it matches a local (to that document) "explicit" `std:ref` target, then link to that and stop - Note, currently only `std:ref` domain/type are supported, e.g. not `math` etc. That's more difficult and can come later 2. If it matches a local (to that document) "implicit" heading slug, then link to that and stop 3. If using docutils (i.e. single-page) build, then stop here and emit a `myst.xref_missing` warning 4. If using sphinx then create a `pending_xref` node, and hand-off to sphinx's "any" resolver, which takes effect once all documents have been read: - This first tries to resolve against a local (to the project) reference and, if matching, stops - Otherwise also try to match against any intersphinx reference - Otherwise emit a ~~`myst.ref`~~ `myst.xref_missing` warning If the text is explicit, e.g. `[text](#id)`, that text is used, otherwise a determination of implicit text is attempted, e.g. based on the section title or figure caption.
Ok, I have removed the following content, which is all things about intersphinx. I am opting to just kick that over to another MEP that can come in at any time. That is where most of the questions were, and I think the rest is actually already implemented in all parsers (maybe not released yet). @chrisjsewell can you take a look soon, hopefully nothing left that is outstanding, then we can get this in and turn it to active and get a bit wider review. This content was removed:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, See comments 😄
Ok, incorporated all of the reviews except the I agree that it is legacy python -- but that isn't a bad thing, it was in use for ~25 years and it already is existing in MyST. I think leaning on that rather than introducing another thing to remember is better. Anything we come up with is going to be pretty arbitrary. I am opting to not change what is already there in MyST/RST for the roles, and leave the |
But what does |
Nothing. This isn't new behaviour it is what Sphinx/RST/MyST already supports for the As an alternative to move this forward, we could say in the enumeration section:
And also paraphrase the existing behaviour. |
Sphinx specifically marks in the code that this is the "old style" (i.e. legacy) format: https://github.com/sphinx-doc/sphinx/blob/30f347226fa4ccf49b3f7ef860fd962af5bdf4f0/sphinx/domains/std.py#L902 I just don't feel we should base our solution on something that sphinx has already deemed to be subpar, and is essentially only supporting for back-compatibility I also don't think, for a "new" part of the spec, we should be already be fragmenting into different ways to do the same thing. We should really just pick one and go with that. But basically; if you change I would also highlight a key difference with Sphinx After talking here, I actually feel using only the this could also be extensible, if we / other implementations wanted to add additional placeholders The key hesitation I have though, is that braces |
I think that if we can't get to consensus on this quickly, then we should just remove the "title and number interpolation syntax" aspect of the MEP, and leave it to implementations to define this (and perhaps use numref as an example and note well visit this in the future). We can make this a targeted MEP in the future if it's important to standardize. If y'all think it's crucial to block the MEP on this topic then that's fine too, but IMO it doesn't feel like something worth blocking on if it requires ongoing discussion. |
I am good with that, this is exactly the same as the "new" sphinx syntax, so we aren't introducing anything new here. |
Thanks @rowanc1. For example, you could theoretically get something like this Do you think thats not a bit eurgh? Also to clarify (and maybe update this in the mep), does |
I have clarified that I agree that all the brackets that could be get visually messy, but I don't think that it will be common in practice. Most of the time people will use the default auto-reference (i.e. if coming from |
yep it is not the end of the world, but something I did want to emphasize.
I always used http://tug.ctan.org/tex-archive/macros/latex/contrib/cleveref/cleveref.pdf 😉 , shame we can't do reference "concatenation", but let's not get ahead of ourselves Almost there although I just noticed something.... |
3b77a97
to
c8ca2d3
Compare
A few comments and questions from coming into this fresh, nothing to stop this going ahead as is though:
Overall though this is a great enhancement and a well thought though MEP 👏🏼 - definitely I don't want to be writing or thinking about any of the other cross reference variants - |
| External URL | `<https://example.com>` | `[](https://example.com)` | | ||
| Local file download | `<path:file.txt>` | `[](file.txt)` | | ||
| File download (explicit) | `<path:file.md>` | `[](path:file.md)` | | ||
| Project document | `<project:file.md>` | `[](file.md)` | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
from the table here I found some of the ambiguity confusing. The syntax is fine though, it was just the way it was expressed in the MEP -- but reading on, the Downloads section below does make it clearer what is going on between [](path:file.md)
and [](file.md)
which is (i) download file that is also in the TOC and (ii) link to a file in the TOC(?)
So I think that is fine.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The changes since my last review look good!
Only one small comment in the Specification AST
section to make it slightly more clear we are changing the existing myst-spec
link
(and a pointer to where we have already implemented the changes).
Co-authored-by: Franklin Koch <franklin@curvenote.com>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This all sounds great to me. I think the new syntax will be extremely convenient.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have two minor suggestions - I'd appreciate the 2nd in particular being addressed, but don't consider ti a blocker (the first is trivial).
All good from my end now, thanks! 🚀 |
Thank you @fwkoch @fperez @gregcaporaso @stevejpurves @chrisjsewell for the reviews! 🚀 I have brought all of the changes in that you suggested. @stevejpurves I have updated the first time we introduced project/path schemes with a bit of explanatory text, I don't think that this materially changes anything, but does give the reader of the MEP a bit more of an idea of what is to come. @chrisjsewell @fwkoch can you review the change to make sure it is consistent please (added the middle few lines)!
I am hoping that this high-level clarification also helps in some of the challenges you had @stevejpurves with understanding the downloads section. Please let us know if that is the case! |
Co-authored-by: Franklin Koch <franklin@curvenote.com>
yep all good cheers 👍 |
Awesome, thanks @chrisjsewell @fwkoch and @jstac as well! I think that we are meeting all criteria from the MEP process for this being accepted! 🎉 📆 MEP will close Monday March 13th, PT 📆 As this is our first MEP running through the process, I propose we leave this open until Monday March 13th, PT (i.e. an additional five working days) and then if no other @executablebooks/core-team members ask for changes in that time, this is ✅✅✅✅✅✅ For reference:
Thanks again to every one participating as we bootstrap this process. 🚀 |
Approvers included: - @jstac - @gregcaporaso - @fwkoch - @stevejpurves - @chrisjsewell - @rowanc1 Early and other reviews by: - @mmcky - @choldgraf - @agoose77 - @fperez
Hi all - a bit delayed on hitting accept on this MEP, but that did give another 4 days beyond the deadline to have any other feedback. There hasn't been any, and we have the required conditions to merge the MEP! I am going to squash merge this in now, and will coordinate a plan to update myst-spec over the next few weeks to reflect this MEP! Thank you again for everyone participating in this process and helping bootstrap these MEPs into existence, this is the first of many enhancements that will improve MyST over the coming years. 🚀 |
Wooo! Thanks Rowan for all of your work spearheading this one, and to everybody else for writing, commenting, discussing, etc. |
📖 Read the MEP Here
📆 MEP will close Monday March 13th, 2023, PT 📆
The current draft with most comments/todos resolved, the Companion issue for the MEP can host overall discussions.
Outstanding issues / questions:
agree on using three "schemes"/protocols (project/path/myst). There is some redundancy here and we can possibly just simplify to(removed)myst
, but we should make sure we don't loose anything. Alternatively we could go in the other direction, addingdownload
instead ofpath
?%t
, which is similar toFig. %s
). In sphinx this is{name}
, which can also be supported, but maybe not mentioned in docs, etc. See @choldgraf response here - choosing%t
.update(removed intersphinx)python?py:class
-->python:py:class
Doc updates / TODOs
Current Status:
DRAFT
. Changing toACTIVE
needs to address above points, do a final pass, update the name of the doc and the ID.We will aim to change this to active for review by wider stakeholders and review (aiming to take @mmcky through in part on Monday) in the next few days and start to get their review.