Add live rendering of /changelog entries #1052

StanczakDominik · 2021-03-02T10:58:21Z

This uses https://github.com/OpenAstronomy/sphinx-changelog (@Cadair's new toy) to render our changelog entries on documentation builds during tests. Figured we could do a test run for him. 😄

Cadair · 2021-03-02T10:59:34Z

docs/whatsnew/0.6.0.rst

@@ -0,0 +1,5 @@
+Plasmapy v0.6.0 (to be released mid-march)


You probably don't need the title, towncrier will render one.

Fair point!

It does, however, set the title to Plasmapy 0.5.1.dev87+g7438c409.d20210301 (2021-03-02), a bugfix release. I don't mind setting the title manually to 0.6.0 once we've got it out the door, so I'll just remove the custom title for now.

If the next release that will be made off of your master branch is going to be v0.6.0 you should add a v6.0.0 tag on master so that setuptools_scm knows what version to render. As described here: https://packaging-guide.openastronomy.org/en/latest/releasing.html#releasing-from-branches

codecov · 2021-03-02T11:00:38Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.86%. Comparing base (6a161f0) to head (ef310db).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1052   +/-   ##
=======================================
  Coverage   96.86%   96.86%           
=======================================
  Files          70       70           
  Lines        6864     6864           
=======================================
  Hits         6649     6649           
  Misses        215      215

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

lifted with love from https://github.com/OpenAstronomy/sphinx-changelog/blob/a15f8adee6c322c618932291381a3f39c369f427/changelog/template.rst

Cadair · 2021-03-02T11:40:02Z

changelog/template.rst

@@ -0,0 +1,19 @@
+{% for section, _ in sections.items() %} {% set underline = underlines[0] %}{% if section %}{{section}} {{ underline * section|length }}{% set underline = underlines[1] %}


have you modified this? if not you shouldn't need it, I only added it to upstream to test it as astropy customised it.

Yeah, I just copied it over - my bad. I was trying to fix https://github.com/PlasmaPy/PlasmaPy/pull/1052/checks?check_run_id=2012587897#step:6:643 this test failure, where the documentation is built within this tox env:

PlasmaPy/tox.ini

Lines 39 to 44 in 6a161f0

[testenv:build_docs]

changedir = {toxinidir}

extras = dev

setenv =

HOME = {envtmpdir}

commands = sphinx-build docs docs/_build/html -W -b html

For some reason, it seems to be running into

https://github.com/OpenAstronomy/sphinx-changelog/blob/90e565cb35e3f80bdebd6da358ecfdc9d2ac9b14/sphinx_changelog/towncrier.py#L33

with config = None, which implies that this part

https://github.com/twisted/towncrier/blob/7f209109513534d4c3e9defc732fa43ce0ff99aa/src/towncrier/_settings.py#L60-L65

cannot locate pyproject.toml:

PlasmaPy/pyproject.toml

Lines 5 to 9 in 6a161f0

[tool.towncrier]

package = "plasmapy"

filename = "CHANGELOG.rst"

directory = "changelog/"

issue_format = "`#{issue} <https://github.com/plasmapy/plasmapy/pull/{issue}>`__"

which might warrant a if config is None or config["template"] is None in sphinx-changelog and definitely warrants more debugging on our end to figure out what happens to pyproject.toml 😅

This reverts commit f92cedf.

This reverts commit e37de98.

docs/whatsnew/0.6.0.rst

Co-authored-by: Stuart Mumford <[email protected]>

Cadair · 2021-03-02T13:59:19Z

@StanczakDominik I just pushed a new rc of the changelog package if you want to restart it and try again. It should at least give a better error now and then hopefully we can see what's going on.

StanczakDominik · 2021-03-02T14:04:41Z

Yup, now RTD is broken, and note that it was building correctly before the config change. This is definitely something about our tox config, so don't worry about it too much - I'll figure it out later (busy elsewhere atm) and report back!

This reverts commit b3b90a1.

Cadair · 2021-03-02T14:21:25Z

I am very confused as to why your tox config would be busting this, it should be relative to the rst file.

docs/whatsnew/0.6.0.rst

Co-authored-by: Stuart Mumford <[email protected]>

rocco8773 · 2021-03-03T01:04:47Z

With respect to the wrong version being displayed for the "live" changelog, it appears when RTD is building and installing plasmapy that it is not respecting the SCM version. Here's a screenshot from the last RTD build of this PR...

If I go back to the last RTD build of branch v0.5.x then the SCM version is respected.

The only difference I can see in the build log between these two cases is which versions of setuptools-scm and setuptools are used. setuptools-scm==4.1.2 & setuptools==51.0.0 are used when SCM is respected (later case) and setuptools-scm==5.0.1 and setuptools==54.0.0 are used when SCM is NOT respected (former case). Maybe try back versioning these two to see if it resolves the issue.

StanczakDominik · 2021-03-03T06:17:08Z

I think this is a relevant clue. @Cadair, in the comment earlier you wrote:

If the next release that will be made off of your master branch is going to be v0.6.0 you should add a v6.0.0 tag on master so that setuptools_scm knows what version to render. As described here: https://packaging-guide.openastronomy.org/en/latest/releasing.html#releasing-from-branches

I read the docs, but (here's an opportunity to improve it, and I'll gladly do so once we've cleared this up): are you saying that, right now, when the next release is not due for at least a week, we should put a tag called v0.6.0dev (dev seems implied by the docs) on the latest commit on master to let setuptools-scm know the version to render?

Cadair · 2021-03-03T10:06:38Z

There are two things at work here.

Firstly, you have the fact that setuptools_scm will by default only increment the bugfix version. This means that if you want to increment the major (or minor) version you need to tag to tell it to do so.

we should put a tag called v0.6.0dev (dev seems implied by the docs) on the latest commit on master to let setuptools-scm know the version to render?

yes. I am not sure what workflow PlasmaPy uses, but if you tag all your releases off branches like sunpy & astropy do then you end up with the situation where your master branch has no tags on it. This means when setuptools_scm looks for the latest tag (it runs git describe) it finds some old tag which is out of date. If you don't release off branches, it will find the previous tag, and only increment the bugfix version.

Both of these issues can be fixed by adding a "start of development" tag when a new major release cycle is started. For sunpy this means at the point where the feature freeze branch is split off from master we add a vX.Y.dev tag to master so that all the version numbers on master from that point take the form of v3.0.dev12345.

(This really is only needed if you release off master to make your development versions "correct", obviously when you tag the final release setuptools_scm will get it right).

Secondly, RTD throws it's own sabo in the works by doing a shallow clone. This means that it likely doesn't fetch all of the tags, which means that git describe and therefore setuptools_scm doesn't read the version correctly. The best way to fix this is to ask RTD nicely to disable shallow clone for your builds. e.g. readthedocs/readthedocs.org#5648

rocco8773 · 2021-03-03T22:56:47Z

Secondly, RTD throws it's own sabo in the works by doing a shallow clone. This means that it likely doesn't fetch all of the tags, which means that git describe and therefore setuptools_scm doesn't read the version correctly. The best way to fix this is to ask RTD nicely to disable shallow clone for your builds. e.g. readthedocs/readthedocs.org#5648

This! I think this is causing the version issues I was describing in my previous post. The master branch is properly tagged (i.e. plamsapy.__version__ properly gives 0.5.1.devX right now). Further evidence of this, (if I remember correctly) when @StanczakDominik built the documentation locally this version issue was not present.

It appears the only way to get the DONT_SHALLOW_CLONE flag activated is to contact RTD admin via email or opening an issue, see https://docs.readthedocs.io/en/stable/guides/feature-flags.html and readthedocs/readthedocs.org#5031 (comment).

StanczakDominik · 2021-03-04T05:54:18Z

Yup, that would be it. However, I don't want to put more strain on RTD's resources by making them download our entire repo's history (I'll do some comparisons on the bandwidth necessary later) for each build just so the version renders nicely, so I wonder if this is something we could side step on our own.

StanczakDominik · 2021-03-04T06:05:17Z

Sounds like https://stackoverflow.com/a/41949974 might work?

…y into sphinx-changelog

StanczakDominik · 2021-03-04T06:41:05Z

Nope, that didn't help matters. All right, I'll ask for the feature flag :)

StanczakDominik · 2021-03-08T13:38:41Z

This should now work; if not, I'll tinker with the tags afterwards. :)

Add live rendering of /changelog entries

7d967f2

StanczakDominik added docs PlasmaPy Docs at http://docs.plasmapy.org PDD labels Mar 2, 2021

Cadair reviewed Mar 2, 2021

View reviewed changes

StanczakDominik added 2 commits March 2, 2021 12:03

Changelog entry, title removal

a6364e3

Add template as per OA repo

e37de98

lifted with love from https://github.com/OpenAstronomy/sphinx-changelog/blob/a15f8adee6c322c618932291381a3f39c369f427/changelog/template.rst

Cadair reviewed Mar 2, 2021

View reviewed changes

StanczakDominik added 3 commits March 2, 2021 12:42

Setting for template

f92cedf

Revert "Setting for template"

caaab32

This reverts commit f92cedf.

Revert "Add template as per OA repo"

8e6a46b

This reverts commit e37de98.

Cadair reviewed Mar 2, 2021

View reviewed changes

docs/whatsnew/0.6.0.rst Outdated Show resolved Hide resolved

Update docs/whatsnew/0.6.0.rst

b3b90a1

Co-authored-by: Stuart Mumford <[email protected]>

Revert "Update docs/whatsnew/0.6.0.rst"

c30e852

This reverts commit b3b90a1.

Cadair reviewed Mar 2, 2021

View reviewed changes

docs/whatsnew/0.6.0.rst Outdated Show resolved Hide resolved

Update docs/whatsnew/0.6.0.rst

e1828e6

Co-authored-by: Stuart Mumford <[email protected]>

namurphy approved these changes Mar 2, 2021

View reviewed changes

StanczakDominik added 4 commits March 4, 2021 07:17

Try getting release info as per scm docs

2e95676

Merge branch 'sphinx-changelog' of github.com:StanczakDominik/PlasmaP…

19c1c3b

…y into sphinx-changelog

Well, it's definitely morning and I ain't had tea yet

5df3705

*sip* ahh

ef310db

StanczakDominik mentioned this pull request Mar 4, 2021

Enable DONT_SHALLOW_CLONE for PlasmaPy readthedocs/readthedocs.org#7980

Closed

StanczakDominik merged commit 0c9b3c4 into PlasmaPy:master Mar 8, 2021

StanczakDominik deleted the sphinx-changelog branch March 8, 2021 13:38

StanczakDominik added this to the 0.6.0 milestone Mar 12, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add live rendering of /changelog entries #1052

Add live rendering of /changelog entries #1052

StanczakDominik commented Mar 2, 2021

Cadair Mar 2, 2021

StanczakDominik Mar 2, 2021

StanczakDominik Mar 2, 2021 •

edited

Loading

Cadair Mar 2, 2021

codecov bot commented Mar 2, 2021 •

edited

Loading

Cadair Mar 2, 2021

StanczakDominik Mar 2, 2021

Cadair commented Mar 2, 2021

StanczakDominik commented Mar 2, 2021

Cadair commented Mar 2, 2021

rocco8773 commented Mar 3, 2021

StanczakDominik commented Mar 3, 2021

Cadair commented Mar 3, 2021

rocco8773 commented Mar 3, 2021 •

edited

Loading

StanczakDominik commented Mar 4, 2021

StanczakDominik commented Mar 4, 2021

StanczakDominik commented Mar 4, 2021

StanczakDominik commented Mar 8, 2021

		@@ -0,0 +1,19 @@
		{% for section, _ in sections.items() %} {% set underline = underlines[0] %}{% if section %}{{section}} {{ underline * section\|length }}{% set underline = underlines[1] %}

	[testenv:build_docs]
	changedir = {toxinidir}
	extras = dev
	setenv =
	HOME = {envtmpdir}
	commands = sphinx-build docs docs/_build/html -W -b html

	[tool.towncrier]
	package = "plasmapy"
	filename = "CHANGELOG.rst"
	directory = "changelog/"
	issue_format = "`#{issue} <https://github.com/plasmapy/plasmapy/pull/{issue}>`__"

Add live rendering of /changelog entries #1052

Add live rendering of /changelog entries #1052

Conversation

StanczakDominik commented Mar 2, 2021

Cadair Mar 2, 2021

Choose a reason for hiding this comment

StanczakDominik Mar 2, 2021

Choose a reason for hiding this comment

StanczakDominik Mar 2, 2021 • edited Loading

Choose a reason for hiding this comment

Cadair Mar 2, 2021

Choose a reason for hiding this comment

codecov bot commented Mar 2, 2021 • edited Loading

Codecov Report

Cadair Mar 2, 2021

Choose a reason for hiding this comment

StanczakDominik Mar 2, 2021

Choose a reason for hiding this comment

Cadair commented Mar 2, 2021

StanczakDominik commented Mar 2, 2021

Cadair commented Mar 2, 2021

rocco8773 commented Mar 3, 2021

StanczakDominik commented Mar 3, 2021

Cadair commented Mar 3, 2021

rocco8773 commented Mar 3, 2021 • edited Loading

StanczakDominik commented Mar 4, 2021

StanczakDominik commented Mar 4, 2021

StanczakDominik commented Mar 4, 2021

StanczakDominik commented Mar 8, 2021

StanczakDominik Mar 2, 2021 •

edited

Loading

codecov bot commented Mar 2, 2021 •

edited

Loading

rocco8773 commented Mar 3, 2021 •

edited

Loading