Fix Sphinx toctree warnings from included CHANGELOG.md #5135

stevepiercy · 2023-08-27T23:19:08Z

See #4422

Prepend CHANGELOG.md with html_meta stuff for SEO.
Manually copy CHANGELOG.md into docs/source/release-nots/index.md. This step might be automated via release-it.
Use a relative symlink from inside the volto docs directory to the news directory at the volto root.
Only check changelog entries when running docs-linkcheckbroken in volto.
Find news items for docs-linkcheckbroken only in volto
Remove non-existent excluded files.
Suppress warning for news items

This PR needs to be merged before its counterpart in documentation will work: plone/documentation#1527

To test locally, checkout the branch linkcheck-news-volto in both documentation and volto.

See #4422 - Prepend CHANGELOG.md with `html_meta` stuff for SEO.

…This step might be automated via release-it.

…news directory at the volto root.

…olto.

netlify · 2023-08-27T23:19:15Z

✅ Deploy Preview for volto canceled.

Name	Link
🔨 Latest commit	`24e8d24`
🔍 Latest deploy log	https://app.netlify.com/sites/volto/deploys/653b89b49491df00082aabc4

…e cleaned up once confirmed.

cypress · 2023-08-27T23:40:10Z

Passing run #7066 ↗︎

0	561	20	0	0

Details:

Try more random shell commands
Project: Volto	Commit: `49de905e32`
Status: Passed	Duration: 15:39 💡
Started: Aug 30, 2023 7:48 AM	Ended: Aug 30, 2023 8:04 AM

_{This comment has been generated by cypress-bot as a result of this
project's GitHub integration settings.}

stevepiercy · 2023-08-27T23:51:36Z

linkcheckbroken should have failed. I think it is not reading the files in news. I need to dig into this more later.

stevepiercy · 2023-08-28T03:49:45Z

Sphinx does not read the files in /news. It appears that the required symlink is never created. Would it be better to commit a symlink to the repo (probably not) or find a GitHub workflow step that will create the symlink? My GitHub Workflow DuckDuckFu has not turned up anything obvious.

Add echos to see whether it gets hit or not. Try creating a symlink in make docs-linkcheckbroken.

stevepiercy · 2023-08-28T04:50:57Z

w00t! Got the symlink to work to news. Now I need to make the workflow fail when linkcheck fails.

…s never called).

stevepiercy · 2023-08-28T05:01:36Z

YAY! It fails! https://github.com/plone/volto/actions/runs/5995760347/job/16259268890?pr=5135#step:7:242

Now to clean them up so it should pass on the next run.

…tation build should pass.

…psie)

stevepiercy · 2023-08-28T06:08:15Z

Shoot, it was failing for something besides a bad link in news. I could not spot the difference between plone/documentation and volto workflows and Makefiles that would cause this. So close!

docs/source/index.md

…docs/source/release-notes/index.md, add, commit, and push.

stevepiercy · 2023-10-10T07:42:24Z

@sneridagh @davisagli this is ready for review. Note that I modified package.json, which requires extra care.

davisagli

One main comment here -- I think we can simplify what is done in the "after:bump" hook, since release-it already commits changes that are made while bumping the version.

I'll leave final approval for @sneridagh, since it's important for him to be familiar with the approach here in case something goes wrong when he actually makes a release.

docs/source/index.md

davisagli · 2023-10-10T15:29:29Z

package.json

@@ -187,7 +187,7 @@
        "yarn i18n",
        "git add locales"
      ],
-      "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version} && make corepackagebump VERSION=${version}",
+      "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version} && make corepackagebump VERSION=${version} && cp CHANGELOG.md docs/source/release-notes/index.md && git add docs/source/release-notes/index.md && git commit -m 'copy CHANGELOG.md' && git push",


I think you can leave out the git add, git commit, and git push here. release-it already pushes a commit with the changes that are made during this hook.

TIL. Should I pull it out now, or let @sneridagh fiddle around with it?

I'd move it to a makefile command (as the corepackagebump). In fact, the corepackagebump actions are similar to these ones.

…ks only in Volto documentation.

sneridagh

@stevepiercy @davisagli please a final look before I merge.

stevepiercy

LGTM! Thank you for the assist!

docs/source/index.md

stevepiercy · 2023-10-10T16:28:43Z

package.json

@@ -187,7 +187,7 @@
        "yarn i18n",
        "git add locales"
      ],
-      "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version} && make corepackagebump VERSION=${version}",
+      "after:bump": "pipx run towncrier build --draft --yes --version ${version} > .changelog.draft && pipx run towncrier build --yes --version ${version} && make corepackagebump VERSION=${version} && cp CHANGELOG.md docs/source/release-notes/index.md && git add docs/source/release-notes/index.md && git commit -m 'copy CHANGELOG.md' && git push",


TIL. Should I pull it out now, or let @sneridagh fiddle around with it?

davisagli

LGTM -- hopefully

* main: Fix Sphinx toctree warnings from included CHANGELOG.md (#5135)

* main: Add support for TS files in add-on registry shadowing system (#5354) Fix Sphinx toctree warnings from included CHANGELOG.md (#5135) Remove regex from sphinx-copybutton config, now that linenos are excl… (#5346) Release 17.3.0 Fix DatetimeWidget on FF, the button default if no type is set is sen… (#5343) Call applyBlockDefaults from addBlock/insertBlock, add initialValue() configuration option for blocks (#5320)

stevepiercy · 2023-11-06T23:05:21Z

I forgot that there is a counterpart in Documentation that needed to be merged at plone/documentation#1527. Merged now. Let's see what happens.

stevepiercy added 6 commits August 27, 2023 16:13

Fix Sphinx toctree warnings from included CHANGELOG.md.

43f8587

See #4422 - Prepend CHANGELOG.md with `html_meta` stuff for SEO.

- Manually copy CHANGELOG.md into docs/source/release-nots/index.md. …

12a3799

…This step might be automated via release-it.

- Use a relative symlink from inside the volto docs directory to the …

4053915

…news directory at the volto root.

- Only check changelog entries when running docs-linkcheckbroken in v…

62da88f

…olto.

- Remove non-existent excluded files.

51f473e

- Suppress warning for news items

43704f5

stevepiercy mentioned this pull request Aug 27, 2023

Fix Sphinx toctree warnings from included CHANGELOG.md plone/documentation#1527

Merged

stevepiercy requested review from davisagli, sneridagh and ksuess August 27, 2023 23:20

Add changelog entry that should test docs-linkcheckbroken, and will b…

3f38187

…e cleaned up once confirmed.

stevepiercy added 5 commits August 27, 2023 21:00

Try creating a symlink in the workflow.

093ced2

Add echos to see whether it gets hit or not. Try creating a symlink in make docs-linkcheckbroken.

Remove symlink creation in docs-linkcheckbroken

3f7d9ed

flip source and target

ece8016

Tricksy ln syntax

76ae6c7

Remove create symlink from workflow

05bd87c

Fail when docs-linkcheckbroken is called instead of test (which i…

eb047ad

…s never called).

stevepiercy added 4 commits August 27, 2023 22:01

Add the generated symlink docs/source/news to .gitignore.

13d48dc

Remove deliberately broken links from change log, so that the documen…

5296f17

…tation build should pass.

Revert to proper shell command test (which is not a make target, oo…

c6e464d

…psie)

Test one more time to make sure the workflow fails with a bad link.

a11c3aa

davisagli reviewed Aug 29, 2023

View reviewed changes

docs/source/index.md Outdated Show resolved Hide resolved

Update docs/source/index.md

e488977

stevepiercy added 14 commits August 30, 2023 00:11

Try to break docs-linkcheckbroken

2698d87

Does it pass?

c4755cc

Now it should pass because there are no bad links

486670a

Try more random shell commands

49de905

Merge branch 'main' into linkcheck-news-volto

49a0ae6

Temporarily ignore youtube playlists from linkcheck

7ad349f

Attempt to make linkcheckbroken fail

18b01a4

Try binary operators to compare integers instead of strings

fca0d01

Add change log

6d17458

Merge branch 'main' into linkcheck-news-volto

b187a41

Merge branch 'main' into linkcheck-news-volto

5ab0c9e

Merge branch 'main' into linkcheck-news-volto

03c83fb

Update release-notes/index.md by manually copying CHANGELOG.md

a81b5b4

Untested change to the hook that will copy the final CHANGELOG.md to …

ca0ecc3

…docs/source/release-notes/index.md, add, commit, and push.

stevepiercy mentioned this pull request Oct 10, 2023

Sphinx toctree warnings from included CHANGELOG.md #4422

Closed

stevepiercy requested a review from davisagli October 10, 2023 07:41

davisagli reviewed Oct 10, 2023

View reviewed changes

Add comment to explain that we check change log entries for valid lin…

b9bc0f8

…ks only in Volto documentation.

tiberiuichim assigned sneridagh Oct 24, 2023

stevepiercy mentioned this pull request Oct 24, 2023

Include the news folder in the repo FBO documentation git submodule #5336

Closed

Move the copy action from the hook to its own makefile command

24e8d24

sneridagh approved these changes Oct 27, 2023

View reviewed changes

stevepiercy commented Oct 27, 2023

View reviewed changes

davisagli approved these changes Oct 28, 2023

View reviewed changes

sneridagh merged commit c8c0b5c into main Nov 2, 2023
51 checks passed

sneridagh deleted the linkcheck-news-volto branch November 2, 2023 11:52

sneridagh added a commit that referenced this pull request Nov 2, 2023

Merge branch 'main' into addtypesdefinitions

50a1949

* main: Fix Sphinx toctree warnings from included CHANGELOG.md (#5135)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix Sphinx toctree warnings from included CHANGELOG.md #5135

Fix Sphinx toctree warnings from included CHANGELOG.md #5135

stevepiercy commented Aug 27, 2023 •

edited

netlify bot commented Aug 27, 2023 •

edited

cypress bot commented Aug 27, 2023 •

edited

stevepiercy commented Aug 27, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Oct 10, 2023

davisagli left a comment

davisagli Oct 10, 2023

stevepiercy Oct 10, 2023

sneridagh Oct 27, 2023

sneridagh left a comment

stevepiercy left a comment

stevepiercy Oct 10, 2023

davisagli left a comment

stevepiercy commented Nov 6, 2023

Fix Sphinx toctree warnings from included CHANGELOG.md #5135

Fix Sphinx toctree warnings from included CHANGELOG.md #5135

Conversation

stevepiercy commented Aug 27, 2023 • edited

netlify bot commented Aug 27, 2023 • edited

✅ Deploy Preview for volto canceled.

cypress bot commented Aug 27, 2023 • edited

Passing run #7066 ↗︎

stevepiercy commented Aug 27, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Aug 28, 2023

stevepiercy commented Oct 10, 2023

davisagli left a comment

Choose a reason for hiding this comment

davisagli Oct 10, 2023

Choose a reason for hiding this comment

stevepiercy Oct 10, 2023

Choose a reason for hiding this comment

sneridagh Oct 27, 2023

Choose a reason for hiding this comment

sneridagh left a comment

Choose a reason for hiding this comment

stevepiercy left a comment

Choose a reason for hiding this comment

stevepiercy Oct 10, 2023

Choose a reason for hiding this comment

davisagli left a comment

Choose a reason for hiding this comment

stevepiercy commented Nov 6, 2023

stevepiercy commented Aug 27, 2023 •

edited

netlify bot commented Aug 27, 2023 •

edited

cypress bot commented Aug 27, 2023 •

edited