Write changelog in markdown using MyST #941

weiji14 · 2021-02-20T23:38:34Z

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:

Install myst-parser following https://myst-parser.readthedocs.io/en/v0.13.5/using/intro.html
Use h2 title (##) for each Release vX.Y.Z header title
Use h3 title (###) for sub-titles under each Release (i.e. New Changes, Bug Fixes, etc)
Sort order of "Highlights", "New Features", "Enhancements", "Documentation", "Bug Fixes", "Maintenance", and "Deprecations" subsections (see Update the release drafter workflow and configurations #885 (comment))

Fixes #885, companion PR to #907.

Reminders

Run make format and make check to make sure the code follows the style guide.
Add tests for new features or tests that would have caught the bug that you're fixing.
Add new public functions/methods/classes to doc/api/index.rst.
Write detailed docstrings for all functions/methods.
If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

/format: automatically format and lint the code
/test-gmt-dev: run full tests on the latest GMT development version

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

.github/release-drafter.yml

weiji14 · 2021-02-21T00:14:02Z

.github/release-drafter.yml

@@ -15,16 +15,19 @@ categories:
    label: 'deprecation'
 exclude-labels:
  - 'skip-changelog'
+category-template: '### $TITLE'


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

It seems commonmark still doesn't support anchors for headers, so maybe we can do nothing here.

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.

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.

@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.

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.

seisman · 2021-02-21T00:51:51Z

Why not using recommonmark (https://www.sphinx-doc.org/en/master/usage/markdown.html)?

weiji14 · 2021-02-21T01:06:49Z

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

seisman · 2021-02-21T01:14:41Z

Why not using recommonmark (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 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 stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst

Fair enough.

.github/release-drafter.yml

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

Order is now "Highlights", "New Features", "Enhancements", "Deprecations", "Bug Fixes", "Documentation", and "Maintenance".

weiji14

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.

weiji14 · 2021-02-22T08:43:34Z

.github/release-drafter.yml

-  - 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'


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?

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.

seisman · 2021-02-22T22:46:47Z

It seems that recent release-drafter releases have more features, for example version-resolver probably can determine if the next version is v0.3.1 or v0.4.0.

seisman · 2021-02-22T22:54:03Z

It seems that recent release-drafter releases have more features, for example version-resolver probably can determine if the next version is v0.3.1 or v0.4.0.

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).

version-resolver:
  minor:
    labels:
      - 'feature'
      - 'enhancement'
  default: patch

weiji14 · 2021-02-22T22:54:12Z

It seems that recent release-drafter releases have more features, for example version-resolver probably can determine if the next version is v0.3.1 or v0.4.0.

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.

seisman

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>

weiji14 added 2 commits February 21, 2021 11:15

weiji14 added the documentation Improvements or additions to documentation label Feb 20, 2021

weiji14 added this to the 0.3.1 milestone Feb 20, 2021

weiji14 commented Feb 20, 2021

View reviewed changes

.github/release-drafter.yml Outdated Show resolved Hide resolved

Use h3 html titles for sub-headings

3871496

vercel bot temporarily deployed to Preview February 20, 2021 23:59 Inactive

weiji14 mentioned this pull request Feb 21, 2021

Update the release drafter workflow and configurations #885

Closed

4 tasks

weiji14 commented Feb 21, 2021

View reviewed changes

vercel bot temporarily deployed to Preview February 21, 2021 00:18 Inactive

weiji14 force-pushed the myst-changelog branch from 65a14ab to 3871496 Compare February 21, 2021 00:19

[skip ci] Fix typo in v0.3.0 DOI link

6058ae0

vercel bot temporarily deployed to Preview February 21, 2021 00:43 Inactive

Let release drafter automatically produce markdown URLs to Pull Requests

2491d96

vercel bot temporarily deployed to Preview February 21, 2021 04:03 Inactive

seisman reviewed Feb 21, 2021

View reviewed changes

.github/release-drafter.yml Show resolved Hide resolved

.github/release-drafter.yml Outdated Show resolved Hide resolved

[skip ci] Add missing brackets back to change-template string

634164b

Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

vercel bot temporarily deployed to Preview February 21, 2021 04:54 Inactive

weiji14 added 2 commits February 22, 2021 21:37

Merge branch 'master' into myst-changelog

5bd3cb6

Reorder categories in release note

e79592c

Order is now "Highlights", "New Features", "Enhancements", "Deprecations", "Bug Fixes", "Documentation", and "Maintenance".

vercel bot temporarily deployed to Preview February 22, 2021 08:41 Inactive

weiji14 commented Feb 22, 2021

View reviewed changes

weiji14 marked this pull request as ready for review February 22, 2021 08:46

weiji14 requested a review from a team February 22, 2021 08:46

seisman approved these changes Feb 22, 2021

View reviewed changes

weiji14 merged commit c93517a into master Feb 22, 2021

weiji14 deleted the myst-changelog branch February 22, 2021 23:09

weiji14 mentioned this pull request Feb 24, 2021

Assigning updates to major and minor releases #945

Closed

seisman mentioned this pull request Jul 2, 2021

Add development toctree and PyGMT team page #1308

Merged

5 tasks

seisman mentioned this pull request Aug 26, 2022

Fix typos in syntax for highlighting #2082

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Write changelog in markdown using MyST #941

Write changelog in markdown using MyST #941

weiji14 commented Feb 20, 2021 •

edited

Loading

weiji14 Feb 21, 2021 •

edited

Loading

seisman Feb 21, 2021

weiji14 Feb 21, 2021

seisman Feb 21, 2021

seisman Feb 22, 2021

weiji14 Feb 22, 2021

seisman commented Feb 21, 2021

weiji14 commented Feb 21, 2021 •

edited

Loading

seisman commented Feb 21, 2021

weiji14 left a comment •

edited

Loading

weiji14 Feb 22, 2021

seisman Feb 22, 2021

seisman commented Feb 22, 2021

seisman commented Feb 22, 2021

weiji14 commented Feb 22, 2021

seisman left a comment

Write changelog in markdown using MyST #941

Write changelog in markdown using MyST #941

Conversation

weiji14 commented Feb 20, 2021 • edited Loading

weiji14 Feb 21, 2021 • edited Loading

Choose a reason for hiding this comment

seisman Feb 21, 2021

Choose a reason for hiding this comment

weiji14 Feb 21, 2021

Choose a reason for hiding this comment

seisman Feb 21, 2021

Choose a reason for hiding this comment

seisman Feb 22, 2021

Choose a reason for hiding this comment

weiji14 Feb 22, 2021

Choose a reason for hiding this comment

seisman commented Feb 21, 2021

weiji14 commented Feb 21, 2021 • edited Loading

seisman commented Feb 21, 2021

weiji14 left a comment • edited Loading

Choose a reason for hiding this comment

weiji14 Feb 22, 2021

Choose a reason for hiding this comment

seisman Feb 22, 2021

Choose a reason for hiding this comment

seisman commented Feb 22, 2021

seisman commented Feb 22, 2021

weiji14 commented Feb 22, 2021

seisman left a comment

Choose a reason for hiding this comment

weiji14 commented Feb 20, 2021 •

edited

Loading

weiji14 Feb 21, 2021 •

edited

Loading

weiji14 commented Feb 21, 2021 •

edited

Loading

weiji14 left a comment •

edited

Loading