-
Notifications
You must be signed in to change notification settings - Fork 219
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
Write changelog in markdown using MyST #941
Conversation
MyST (Markedly Structured Text) for writing Sphinx docs in markdown! Following the installation guide of [myst-parser](https://github.com/executablebooks/myst-parser) at https://myst-parser.readthedocs.io/en/v0.13.5/using/intro.html.
Convert ReST syntax `doc/changes.rst` to MyST syntax `doc/changes.md`. Mostly changing the GitHub URLs from into the nicer markdown format Modified template at release-drafter.yml such that: - A h2 title (##) is used for each Release vX.Y.Z header. - Alt text for DOI button is more descriptive with version info
@@ -15,16 +15,19 @@ categories: | |||
label: 'deprecation' | |||
exclude-labels: | |||
- 'skip-changelog' | |||
category-template: '### $TITLE' |
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.
Need help to find a way to make the subheaders (e.g. for v0.2.1 enhancements) a proper permalink. I.e. something like https://pygmt-git-myst-changelog.gmt.vercel.app/changes.html#v0-2-1-enhancements instead of https://pygmt-git-myst-changelog.gmt.vercel.app/changes.html#id3
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.
It seems commonmark still doesn't support anchors for headers, so maybe we can do nothing here.
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.
Maybe do it in sphinx instead? I see https://stackoverflow.com/questions/15394347/adding-a-cross-reference-to-a-subheading-or-anchor-in-another-page#comment79146992_40225340 pointing to https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document.
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 autosectionlabel_prefix_document configuration variable can be used to make headings which appear multiple times but in different documents unique.
Useful for avoiding ambiguity when the same section heading appears in different documents.
I don't think it works for us.
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.
@weiji14 As we have no solution for the custom anchors, do you think we should not use h3 headers, but just use bold headings, i.e., use **Documentation**
, not ### Documentation
.
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.
Would stick with h3 headers. Even without the permalink anchors, it'll still be easier for users to navigate quickly to the subsection on the sidebar:
And people could still point to the v0.3.0 highlights using https://www.pygmt.org/v0.3.0/changes.html#highlights, and so on for v0.4.0 and beyond.
65a14ab
to
3871496
Compare
Why not using recommonmark (https://www.sphinx-doc.org/en/master/usage/markdown.html)? |
The markdown-it parser used in MyST is about two times faster than the commonmark_py parser used in recommonmark (see https://markdown-it-py.readthedocs.io/en/latest/other.html#performance). Also because I didn't know about Recommonmark, though MyST does seem better documented and actively maintained? See also https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst |
Fair enough. |
Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
Order is now "Highlights", "New Features", "Enhancements", "Deprecations", "Bug Fixes", "Documentation", and "Maintenance".
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 autosectionlabel_prefix_document configuration variable can be used to make headings which appear multiple times but in different documents unique.
Useful for avoiding ambiguity when the same section heading appears in different documents.
I don't think it works for us.
Ok, this PR is ready for final review @GenericMappingTools/python-maintainers. Sorry that the changes.rst
to changes.md
rename doesn't have a nice diff, but you can preview things at https://pygmt-git-myst-changelog.gmt.vercel.app/changes.html. The permalink/anchor issue mentioned at #941 (comment) is fairly minor so I'll just let it be.
- title: 'Documentation' | ||
label: 'documentation' | ||
- title: 'Deprecations' | ||
label: 'deprecation' | ||
- title: 'Bug Fixes' | ||
label: 'bug' | ||
- title: 'Documentation' | ||
label: 'documentation' | ||
- title: 'Maintenance' | ||
label: 'maintenance' | ||
- title: 'Deprecations' | ||
label: 'deprecation' |
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.
Categories have been reordered following #885 (comment). Do we want to reorder things in the previous release changelogs (i.e. v0.1.0 to v0.3.0) or just keep them as they were?
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.
Categories have been reordered following #885 (comment).
Looks good to me.
Do we want to reorder things in the previous release changelogs (i.e. v0.1.0 to v0.3.0) or just keep them as they were?
No need to reorder the old entries.
It seems that recent release-drafter releases have more features, for example |
If I understand it correctly, the following setting means that if any PR labeled with "feature" or "enhancement" is merged into master branch, the next version will be a minor release (i.e., v0.4.0), otherwise it's a patch release (i.e., v0.3.1). However, sometimes we merge PRs with "enhancement" but may don't want to bump the minor version (e.g., #952).
|
Oo, that does look fancy! But let's leave that to a separate Pull Request as we'll need to document that '$RESOLVED_VERSION` feature in MAINTENANCE.md too. Or I can include it in #907. |
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 PR is good to merge. We can change any settings in future PRs.
* Install myst-parser and add it to sphinx extension list MyST (Markedly Structured Text) for writing Sphinx docs in markdown! Following the installation guide of [myst-parser](https://github.com/executablebooks/myst-parser) at https://myst-parser.readthedocs.io/en/v0.13.5/using/intro.html. * Rename doc/changes.rst to doc/changes.md and convert to markdown Convert ReST syntax `doc/changes.rst` to MyST syntax `doc/changes.md`. Mostly changing the GitHub URLs from into the nicer markdown format Modified template at release-drafter.yml such that: - A h2 title (##) is used for each Release vX.Y.Z header. - Alt text for DOI button is more descriptive with version info * Use h3 html titles for sub-headings * Let release drafter automatically produce markdown URLs to Pull Requests * Reorder categories in release note Order is now "Highlights", "New Features", "Enhancements", "Deprecations", "Bug Fixes", "Documentation", and "Maintenance". Co-authored-by: Dongdong Tian <seisman.info@gmail.com>
Description of proposed changes
MyST (Markedly Structured Text) allows us to write Sphinx documentation entirely in markdown (technically using Commonmark). I.e. think ReST (Restructured Text) but in Markdown! MyST is a fairly young project (first published PyPI release on 6 Mar 2020), but it looks pretty awesome already!
This MyST parser should address @seisman's comment at #885 (comment) on the pain of having to convert the markdown changelog generated by Release Drafter into ReST syntax. In other words, we should be able to just copy and paste things directly from https://github.com/GenericMappingTools/pygmt/releases, all in markdown!
Documentation preview is at https://pygmt-git-myst-changelog.gmt.vercel.app/changes.html. This should look pretty much the same as https://www.pygmt.org/v0.3.0/changes.html (point out any inconsistencies if you spot any).
TODO:
Fixes #885, companion PR to #907.
Reminders
make format
andmake check
to make sure the code follows the style guide.doc/api/index.rst
.Slash Commands
You can write slash commands (
/command
) in the first line of a comment to performspecific operations. Supported slash commands are:
/format
: automatically format and lint the code/test-gmt-dev
: run full tests on the latest GMT development version