Skip to content
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

πŸš€ RELEASE: 0.17.0 #507

Merged
merged 3 commits into from Feb 11, 2022
Merged

πŸš€ RELEASE: 0.17.0 #507

merged 3 commits into from Feb 11, 2022

Conversation

chrisjsewell
Copy link
Member

@chrisjsewell chrisjsewell commented Jan 19, 2022

I think this is just about good to go!

I have essentially been running a "feedback loop" with executablebooks/MyST-NB#380, to ensure everything will be fine running these changes up to myst-nb and jupyter-book (see executablebooks/jupyter-book#1608)

My only slight "concerns" are:

  1. With ♻️ REFACTOR: Parsing logic of Markdown linksΒ #467, a few people might complain about some subtle changes to link identification (e.g. that links with # are no longer "automatically" treated as external), although it should be very rare
  2. With ‼️ BREAKING: Remove dollarmath from default myst_enable_extensionsΒ #505, again people might not notice, and then complain it is not working

I think both these changes are good/necessary, it is just the backward dependency consideration (although I would hope people have suitably pinned to ~=0.16.0)


Breaking changes

Dollarmath is now disabled by default.

You may enable it manually by adding dollarmath to myst_enable_extensions.
If your documentation had syntax like this in it:

$$
e=mc^2
$$

You should ensure that dollarmath is explicitly added to myst_enable_extensions.
See the math extension documentation for more details. by @chrisjsewell in #505

ref: #505

Link parsing has been changed

The MyST Parser will now try to more sensibly parse links that are specified in markdown, with the goal of behaving as users would expect the link to behave. For example, linking to local non-Sphinx files will now cause those local files to be included with your Sphinx build.

This might slightly change the behavior of some markdown links, so double-check your links if you were doing anything non-standard. For example, if you were using link syntax like [link text](link/to/localfile.txt) you should now see more sensible behavior.

See the markdown links/referencing documentation for more details.

ref: #467

What's Changed

Full Changelog: v0.16.1...master

@codecov
Copy link

codecov bot commented Jan 19, 2022

Codecov Report

Merging #507 (efc8152) into master (7654462) will not change coverage.
The diff coverage is 100.00%.

Impacted file tree graph

@@           Coverage Diff           @@
##           master     #507   +/-   ##
=======================================
  Coverage   90.06%   90.06%           
=======================================
  Files          16       16           
  Lines        2103     2103           
=======================================
  Hits         1894     1894           
  Misses        209      209           
Flag Coverage Ξ”
pytests 90.06% <100.00%> (ΓΈ)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files Coverage Ξ”
myst_parser/__init__.py 88.57% <100.00%> (ΓΈ)

Continue to review full report at Codecov.

Legend - Click here to learn more
Ξ” = absolute <relative> (impact), ΓΈ = not affected, ? = missing data
Powered by Codecov. Last update 7654462...efc8152. Read the comment docs.

@chrisjsewell
Copy link
Member Author

Any initial comments @choldgraf @mmcky ?

@mmcky
Copy link
Member

mmcky commented Jan 20, 2022

@chrisjsewell with the breaking change

just two quick questions:

  1. Is there a warning if $$ is "parsed" to tell users of myst-parser to enable the dollarmath extension?
  2. would it be possible to show in the CHANGELOG what the output looks like if a user tries to use $$ with the new version of myst-parser and a note to say the dollarmath extension needs to be turned on.

In the past when there was breaking changes on another project they had that in the CHANGELOG and it was immediately identificable as "oh that's my issue, my output looks like that". I presume it just shows the $$ and the raw math markup?

@mmcky
Copy link
Member

mmcky commented Jan 20, 2022

thanks @chrisjsewell this is looking like a great update.

@befeleme
Copy link

befeleme commented Feb 1, 2022

Hello, when do you plan to release 0.17? I'd like to update it in Fedora as it will work nicely with the new Pygments :) Thank you!

@chrisjsewell
Copy link
Member Author

Hello, when do you plan to release 0.17? I'd like to update it in Fedora as it will work nicely with the new Pygments :) Thank you!

this week πŸ˜„

Just wanted to give time for anyone to raise issues/objections, and double-check the back-breaking changes aren't going to incur too much backlash πŸ˜…

@choldgraf
Copy link
Member

I've added a short section with "breaking changes" to the top comment above to try and explain these two a bit more. Also added a short example per @mmcky's suggestion. Feel free to take or leave as you wish @chrisjsewell - I am +1 on a release πŸ‘

@mmcky
Copy link
Member

mmcky commented Feb 1, 2022

thanks @chrisjsewell on this refactor work. I think it looks great.

This month I would like to do a parse of the developer documentation -- it would be great to fully understand the architecture )(so might arrange a zoom with you) so we can identify / document some ways forward in the future to restore cross-document glue behaviour such as:

  1. use sphinx transforms/post-transforms to resolve (with limited support for various mime types)

I will move that comment to myst-nb as I think it mainly lives at the myst-nb level. I think that is likely to be the biggest "risk" point for that release.

I am +1 on release as well.

@choldgraf
Copy link
Member

Is there anything blocking this release?

@chrisjsewell
Copy link
Member Author

chrisjsewell commented Feb 11, 2022

Ok added changelog, so will merge when tests pass and release

I presume it just shows the $$ and the raw math markup?

@mmcky, no not for HTML output, since mathjax (enabled by default in sphinx) will still parse/render them, which is the point of possible confusion.
IMO this is not a good solution, since it is not output format agnostic; the parser (i.e. markdown-it) should be the one to parse the syntax, then something like mathjax or katex, should simply render it (i.e. convert to HTML), which is what the dollarmath extension enables.
In fact, the ideal solution would be for there to be a mathjax/katex implementation in Python, so we could convert the latex math to html (or other formats) during the sphinx build, similar to what happens with code blocks syntax highlighting via https://pygments.org/. Then you would not need any unnecessary JavaScript running on your page load

@chrisjsewell chrisjsewell marked this pull request as ready for review February 11, 2022 12:14
@chrisjsewell chrisjsewell merged commit e477a75 into master Feb 11, 2022
@chrisjsewell chrisjsewell deleted the release/v0.17.0 branch February 11, 2022 12:15
@mmcky
Copy link
Member

mmcky commented Feb 14, 2022

Thanks for explaining that for me @chrisjsewell that makes a long of sense. It would also stop that load time when you initially load a large page it sometimes blinks as the mathjax gets rendered.

@choldgraf
Copy link
Member

Sent out a tweet about this as well: https://twitter.com/ExecutableBooks/status/1493312075011088388

@chrisjsewell
Copy link
Member Author

Cheers @choldgraf
Note, one more thing may warrant retroactively highlighting in the changelog, is that e.g. [text](#anchor) will no longer work automatically, and instead you should set myst_heading_anchors (see #519)

tapaswenipathak added a commit to tapaswenipathak/OpenMS-docs that referenced this pull request Jun 12, 2022
tapaswenipathak added a commit to tapaswenipathak/OpenMS-docs that referenced this pull request Jun 12, 2022
- executablebooks/MyST-Parser#519
- executablebooks/MyST-Parser#507 (comment)
- https://i.gyazo.com/06ce07fca33afb64e81c687a49fd5008.jpg
- hacks
- https://i.gyazo.com/1c825601041a6d77a83304b36b3c2765.png (#metrics)
- https://i.gyazo.com/723111811021645df0950ab0e1a1648c.png
tapaswenipathak@Tapaswenis-MacBook-Pro OpenMS-docs % myst-anchors -l 4 docs/tutorials/TOPP/quality-control.md
<h1 id="quality-control"></h1>
<h2 id="workflow"></h2>
<h2 id="metrics"></h2>
<h3 id="input-data"></h3>
<h3 id="contaminants"></h3>
<h4 id="required-input-data"></h4>
<h4 id="output"></h4>
<h3 id="fragmentmasserror"></h3>
<h4 id="required-input-data-1"></h4>
<h4 id="output-1"></h4>
<h3 id="missedcleavages"></h3>
<h4 id="required-input-data-2"></h4>
<h4 id="output-2"></h4>
<h3 id="ms2identificationrate"></h3>
<h4 id="required-input-data-3"></h4>
<h4 id="output-3"></h4>
<h3 id="mzcalibration"></h3>
<h4 id="required-input-data-4"></h4>
<h4 id="output-4"></h4>
<h3 id="rtalignment"></h3>
<h4 id="required-input-data-5"></h4>
<h4 id="output-5"></h4>
<h3 id="tic"></h3>
<h4 id="required-input-data-6"></h4>
<h4 id="output-6"></h4>
<h3 id="topnoverrt"></h3>
<h4 id="required-input-data-7"></h4>
<h4 id="output-7"></h4>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants