The "make" commands and filenames below are run in/relative to the
documentation directory.
1. Between releases, EPICS_DEV_SNAPSHOT != "":
"make" generates $(COMMON_DIR)/RELEASE_NOTES.md from new-notes/*.md
and installs it and all the older RELEASE-<ver>.md files into the
$(INSTALL_DOC) directory.
"make release" or "make unrelease" fail with an error message:
"make release" not available, EPICS_DEV_SNAPSHOT not empty
2. Creating a release, so EPICS_DEV_SNAPSHOT == "":
"make" installs all existing RELEASE-<ver>.md files into $(INSTALL_DOC).
3. Creating a release, EPICS_DEV_SNAPSHOT == "", no file exists named
RELEASE-<ver>.md:
"make release" generates RELEASE-<ver>.md from new-notes/*.md and does
"git add" of that; runs "git rm" of new-notes/*.md;
generates $(COMMON_DIR)/RELEASE_NOTES.md with a different introduction;
Installs all RELEASE*.md files into $(INSTALL_DOC).
4. EPICS_DEV_SNAPSHOT == "", RELEASE-<ver>.md exists and was added to
the Git index:
"make unrelease" here undoes the changes the "make release" command
applied to the Git index and restores the deleted new-notes files.
Running "make release" twice in a row could mess up the first generated
RELEASE-<ver>.md file if any new-notes/*.md files were added or the
make-notes.pl script modified between the two, but to recover just
running "make unrelease" and then "make release" again.
4. EPICS_DEV_SNAPSHOT == "", RELEASE-<ver>.md was added to Git but the
file has since been deleted:
"make unrelease" here will also recover the state and restore any deleted
new-notes/*.md files.
5. EPICS_DEV_SNAPSHOT == "", RELEASE-<ver>.md exists but was not added to
the Git index:
"make release" or "make unrelease" fail with an error message:
"make release" not available, RELEASE-<ver>.md exists but isn't in Git
- 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.
Includes instructions on how to generate a new Release-<ver>.md
file at the right time during the release process – it won't work
properly if done earlier.
Adds new-notes files for the PRs already merged.
Future conflicts in the now-deleted RELEASE_NOTES.md file must be
turned into new-notes/PR-nnn.md files when resolving them.
Import all function documentations, return code reference
into the header files, as doc comments,
in the hopes of moving the CAref.html manual to docs.epics-controls.org,
which will be done in a later PR.
Also added doc comments to some other low-hanging fruits,
for example when plain comments where near, or when it was obvious to do so.
