From 5aff8cee308b44544219770fbd93f1810c5449b4 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Sun, 15 Jun 2025 23:25:30 -0500 Subject: [PATCH] Adjust generated RELEASE_NOTES.md - Use a Sphinx/Myst {include} directive to pull the text from all previous RELEASE files into the output, which makes the website sidebar index work properly. - Exclude the RELEASE files from the files given to RTD to publish, they aren't needed now and generate warnings if included. - Updated the intro paragraph in all RELEASE files. --- documentation/Makefile | 2 +- documentation/RELEASE-7.0.1.1.md | 10 +++---- documentation/RELEASE-7.0.2.1.md | 10 +++---- documentation/RELEASE-7.0.2.2.md | 10 +++---- documentation/RELEASE-7.0.2.md | 10 +++---- documentation/RELEASE-7.0.3.1.md | 10 +++---- documentation/RELEASE-7.0.3.md | 10 +++---- documentation/RELEASE-7.0.4.1.md | 10 +++---- documentation/RELEASE-7.0.4.md | 10 +++---- documentation/RELEASE-7.0.5.md | 10 +++---- documentation/RELEASE-7.0.6.1.md | 10 +++---- documentation/RELEASE-7.0.6.md | 10 +++---- documentation/RELEASE-7.0.7.md | 10 +++---- documentation/RELEASE-7.0.8.1.md | 10 +++---- documentation/RELEASE-7.0.8.md | 10 +++---- documentation/RELEASE-7.0.9.md | 10 +++---- documentation/make-notes.pl | 50 +++++++++++++++++++++++--------- 17 files changed, 112 insertions(+), 90 deletions(-) diff --git a/documentation/Makefile b/documentation/Makefile index e1d3d74a7..0f88d446d 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -72,7 +72,7 @@ doxygen: Doxyfile $(DOXYGEN) rtd: doxygen $(API_RST_FILES) $(HEADER_MD_FILES) - rsync -av $(INSTALL_DOC)/ $(RTD_SRC)/ + rsync -av --exclude=RELEASE-*.md $(INSTALL_DOC)/ $(RTD_SRC)/ rsync -av $(HEADER_MD_FILES) $(RTD_SRC)/ rsync -av $(API_RST_FILES) $(RTD_SRC)/ rsync -av ../index.rst ../conf.py $(RTD_SRC)/ diff --git a/documentation/RELEASE-7.0.1.1.md b/documentation/RELEASE-7.0.1.1.md index 95f2035fc..ee61fdcf9 100644 --- a/documentation/RELEASE-7.0.1.1.md +++ b/documentation/RELEASE-7.0.1.1.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.1.1 diff --git a/documentation/RELEASE-7.0.2.1.md b/documentation/RELEASE-7.0.2.1.md index ff8bfda80..edcc19b93 100644 --- a/documentation/RELEASE-7.0.2.1.md +++ b/documentation/RELEASE-7.0.2.1.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.2.1 diff --git a/documentation/RELEASE-7.0.2.2.md b/documentation/RELEASE-7.0.2.2.md index 19c3157c9..27adf0610 100644 --- a/documentation/RELEASE-7.0.2.2.md +++ b/documentation/RELEASE-7.0.2.2.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.2.2 diff --git a/documentation/RELEASE-7.0.2.md b/documentation/RELEASE-7.0.2.md index 24d829dc3..a5b368cd0 100644 --- a/documentation/RELEASE-7.0.2.md +++ b/documentation/RELEASE-7.0.2.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.2 diff --git a/documentation/RELEASE-7.0.3.1.md b/documentation/RELEASE-7.0.3.1.md index ad9a38edd..3f1180243 100644 --- a/documentation/RELEASE-7.0.3.1.md +++ b/documentation/RELEASE-7.0.3.1.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.3.1 diff --git a/documentation/RELEASE-7.0.3.md b/documentation/RELEASE-7.0.3.md index c386b6296..785899a36 100644 --- a/documentation/RELEASE-7.0.3.md +++ b/documentation/RELEASE-7.0.3.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.3 diff --git a/documentation/RELEASE-7.0.4.1.md b/documentation/RELEASE-7.0.4.1.md index 595b06a7c..038f06f43 100644 --- a/documentation/RELEASE-7.0.4.1.md +++ b/documentation/RELEASE-7.0.4.1.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.4.1 diff --git a/documentation/RELEASE-7.0.4.md b/documentation/RELEASE-7.0.4.md index b88c6f409..1567d2c7b 100644 --- a/documentation/RELEASE-7.0.4.md +++ b/documentation/RELEASE-7.0.4.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. ## EPICS Release 7.0.4 diff --git a/documentation/RELEASE-7.0.5.md b/documentation/RELEASE-7.0.5.md index 28105b0f0..cab17a98d 100644 --- a/documentation/RELEASE-7.0.5.md +++ b/documentation/RELEASE-7.0.5.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/RELEASE-7.0.6.1.md b/documentation/RELEASE-7.0.6.1.md index 217a8bb3a..82108bf6a 100644 --- a/documentation/RELEASE-7.0.6.1.md +++ b/documentation/RELEASE-7.0.6.1.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/RELEASE-7.0.6.md b/documentation/RELEASE-7.0.6.md index 6dd31bcd1..a0285bd76 100644 --- a/documentation/RELEASE-7.0.6.md +++ b/documentation/RELEASE-7.0.6.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/RELEASE-7.0.7.md b/documentation/RELEASE-7.0.7.md index 787be2773..5ed0104f5 100644 --- a/documentation/RELEASE-7.0.7.md +++ b/documentation/RELEASE-7.0.7.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/RELEASE-7.0.8.1.md b/documentation/RELEASE-7.0.8.1.md index 22d185c46..4fed2b3de 100644 --- a/documentation/RELEASE-7.0.8.1.md +++ b/documentation/RELEASE-7.0.8.1.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/RELEASE-7.0.8.md b/documentation/RELEASE-7.0.8.md index c084756b4..b9b071467 100644 --- a/documentation/RELEASE-7.0.8.md +++ b/documentation/RELEASE-7.0.8.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/RELEASE-7.0.9.md b/documentation/RELEASE-7.0.9.md index d8f86d8e6..015f50c06 100644 --- a/documentation/RELEASE-7.0.9.md +++ b/documentation/RELEASE-7.0.9.md @@ -1,10 +1,10 @@ # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version diff --git a/documentation/make-notes.pl b/documentation/make-notes.pl index 87d6aa124..a8a4db369 100644 --- a/documentation/make-notes.pl +++ b/documentation/make-notes.pl @@ -72,23 +72,23 @@ sub relVers { } # Reverse sort of the RELEASE-.md filenames -my @OLD_RELS = sort { +my @OLD_REL_FILES = sort { version->parse(relVers($b)) <=> version->parse(relVers($a)); } @ARGV; print $out <<"__REL_INTRO__"; # Release Notes -This document describes changes that were included in the release of -EPICS listed below. -Notes from earlier EPICS releases are now provided in a separate document for -each version in the EPICS 7 series to date. -Release documents are also included for the older Base 3.15 and 3.16 series. +This document describes the changes that were included in the release of EPICS +noted below. Release entries are now provided in a separate document for each +version in the EPICS 7 series, but all are combined into a single page for +publishing on the EPICS website. Separate release documents are also included +from the older Base 3.15 and 3.16 series. The external PVA submodules continue to maintain their own release notes files as before, but the entries describing changes in those submodules since version -7.0.5 have been copied into the associated EPICS Release Notes files, and will -be added to new EPICS Release Notes published in the future. +7.0.5 have been copied into the associated EPICS Release Notes files; they will +also be manually added to new EPICS Release Notes published in the future. __REL_INTRO__ @@ -104,13 +104,35 @@ The changes below have been merged into EPICS since the last published release. __NEW_INTRO__ -print $out map { "$_\n" } @notes, "-----\n\n"; +# Include the text from all the new entries +print $out map { "$_\n" } @notes; -print $out "```{toctree}\n", - ":caption: Previous Releases\n", - ":titlesonly:\n", - map( sprintf("RELEASE-%s.md\n", relVers($_)), @OLD_RELS), - "```\n\n"; +# Add myst include directives to incorporate older release files +foreach my $rfile (@OLD_REL_FILES) { + my $ver = relVers($rfile); + if ($ver =~ m/^7\./) { + print $out <<"__OLD_RELEASE_7__"; +----- + +## EPICS Release $ver + +```{include} ../$rfile +:start-after: EPICS Release $ver +``` + +__OLD_RELEASE_7__ + } + elsif ($ver =~ m/^3\.1[56]/) { + print $out <<"__OLD_RELEASE_3__"; +----- + +```{include} ../$rfile +:heading-offset: 1 +``` + +__OLD_RELEASE_3__ + } +} close $out;