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.
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.
Adds the build target 'sphinx' for manual Sphinx runs, and
installs the output of that under $(INSTALL_HTML)/readthedocs
Adjusted some Sphinx config parameters and titles.
That .pod file will now be converted to .html using the same style as
the individual local documents that it links to.
The dbdToHtml output files now include a header and footer that link to
the ComponentReference.html file (they started pointing to the original
RecordReference.html but that was broken on most people's builds because
we weren't converting that from the original Markdown version).
This commit also adjusts documentation/Makefile to use the build system
properly, and reorders the Doxygen main page index.
