From 70aa9b0135d5093ac2063f934578c1ab836a98fe Mon Sep 17 00:00:00 2001 From: Gianluca Petrillo Date: Mon, 10 Mar 2025 19:42:30 -0500 Subject: [PATCH 1/2] Updated documentation generation scripts * the publishing directory is updated * instructions now mention about the possible need for a container * a slight change in the setup scripts handling a possible setup failure --- doc/scripts/GenerateDocumentation.md | 13 ++++++++++++- doc/scripts/settings.sh | 2 +- doc/scripts/utilities.sh | 2 +- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/scripts/GenerateDocumentation.md b/doc/scripts/GenerateDocumentation.md index caccc5cf6..20d81abd0 100644 --- a/doc/scripts/GenerateDocumentation.md +++ b/doc/scripts/GenerateDocumentation.md @@ -58,6 +58,11 @@ In order to successfully run it, the additional library scripts `settings.sh` and `utilities.sh` must also be in the same directory as the main script. In addition, `experiment_settings.sh` overriding the general settings is also parsed. + +> **NOTE** This script uses the deployment system, currently UPS, to discover +> the version of all the repositories to pull in. UPS must be available in +> the system where the script is run, possibly using a container. + There are two possibilities: * clone the GIT repository altogether, and find the scripts in @@ -74,7 +79,7 @@ Note that the script *must* be executed from outside the `icaruscode` GIT repository, like in the example above. Normally this will clone or _update_ the repository, and run Doxygen on it. -Note that **"update"**: the script `updateLocalDocumentation.sh` **does** mess +Note the word "update": the script `updateLocalDocumentation.sh` **does** mess up with the GIT repository, and while there is some provision not to lose data, if that repository has anything valuable it should be backed up or pushed before running. @@ -133,6 +138,12 @@ web content directory; and before that, the node where this script is ran must have POSIX (e.g. NFS) access to that directory. Enabling these is matter of Fermilab service desk requests. +> **NOTE** If running in a container because of the requirements of the previous +> step, that container needs to bind the appropriate directory (the path is set +> by `PublishBaseDir` variable in `settings.sh`) in read/write mode. +> However, neither the publishing nor the version list update currently require +> access to UPS nor a container. + If the directory already exists, the script will refuse to proceed. This is intentional, to prevent a potentially complex script from unintentionally deleting information on the web site in case of errors or bugs. diff --git a/doc/scripts/settings.sh b/doc/scripts/settings.sh index c0d200698..f22a8d84c 100644 --- a/doc/scripts/settings.sh +++ b/doc/scripts/settings.sh @@ -31,7 +31,7 @@ declare DefaultBranch='master' declare RepoDocSubdir='doc' # where the content is published -declare PublishBaseDir='/web/sites/i/icarus-exp.fnal.gov/htdocs/at_work/software/doc' +declare PublishBaseDir='/pubhosting/sites/i/icarus-exp.fnal.gov/htdocs/at_work/software/doc' # directory of Doxygen generation metadata, relative to Doxygen output directory declare MetadataFileRelPath='meta/doxygen' diff --git a/doc/scripts/utilities.sh b/doc/scripts/utilities.sh index a7e417bd9..39c87dbaf 100644 --- a/doc/scripts/utilities.sh +++ b/doc/scripts/utilities.sh @@ -242,7 +242,7 @@ function ExperimentSetup() { [[ -r "$SetupScript" ]] || FATAL 1 "Can't find setup script for experiment '${Experiment}'." echo "Setting up the UPS area for ${Experiment}..." - source "$SetupScript" + source "$SetupScript" || LASTFATAL "Failed to set up the UPS area." local -r LatestVersion=$(FindLatestUPS "$ExperimentCodeName") From 6c6b95eba8d5da83f7bb897a9e5f44cb86a06f57 Mon Sep 17 00:00:00 2001 From: Gianluca Petrillo Date: Wed, 12 Mar 2025 10:05:55 -0500 Subject: [PATCH 2/2] Updated ROOT Doxigen tag file name in documentation generation scripts --- doc/scripts/GenerateDocumentation.md | 2 +- doc/scripts/updateLocalDocumentation.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) mode change 100644 => 100755 doc/scripts/updateLocalDocumentation.sh diff --git a/doc/scripts/GenerateDocumentation.md b/doc/scripts/GenerateDocumentation.md index 20d81abd0..0946c1dc6 100644 --- a/doc/scripts/GenerateDocumentation.md +++ b/doc/scripts/GenerateDocumentation.md @@ -61,7 +61,7 @@ parsed. > **NOTE** This script uses the deployment system, currently UPS, to discover > the version of all the repositories to pull in. UPS must be available in -> the system where the script is run, possibly using a container. +> the system where the script is run, possibly using a container. There are two possibilities: diff --git a/doc/scripts/updateLocalDocumentation.sh b/doc/scripts/updateLocalDocumentation.sh old mode 100644 new mode 100755 index 902d42dde..c5a018f23 --- a/doc/scripts/updateLocalDocumentation.sh +++ b/doc/scripts/updateLocalDocumentation.sh @@ -156,7 +156,7 @@ function UpdateROOTtag() { ROOTVersionTag="${ROOTVersionTag//.}" echo "Fetching Doxygen tag for ROOT version ${ROOTVersion}" - UpdateTag 'ROOT.tag' "https://root.cern/doc/v${ROOTVersionTag}/ROOT.tag" "ROOT" + UpdateTag 'ROOT.tag' "https://root.cern/doc/v${ROOTVersionTag}/ROOT.tag.gz" "ROOT" } # UpdateROOTtag()