Fixes for Release Script and Doc Post-3.26.0

- Fixed Read the Docs links in README not getting updated properly.
- Fixed `gitrelease.pl --list` ignoring the current release workspace.
  This comes at the cost of having to have that workspace though.
- Re-enabled Read the Docs version activation and updated release doc
  for this.
- Other small fixes for the release doc.

docs/internal/release.rst

@@ -1,6 +1,6 @@
-#######################
-OpenDDS Release Process
-#######################
+###############
+Release Process
+###############
 
 The page provides the steps needed to make and publish a release of OpenDDS.
 
@@ -20,8 +20,7 @@ Temporary Notes
 List of current problems with the release process and their workarounds.
 If there's nothing to note then the list should just consist of ``- N/A``.
 
-- The readthedocs.org version needs to be activated manually after the tag has been pushed.
-  There's a part of the script to do this automatically, but it's only partially working.
+- N/A
 
 ********************
 Prior to the Release
@@ -56,7 +55,6 @@ These are files or the parts of the files that the release script won't be able
   - Run ``./tools/scripts/gitrelease.pl --update-authors`` again to make sure the changes worked.
 
 - Update :ghfile:`README.md` and :doc:`/devguide/building/dependencies` for any platform or dependency changes, such as updates to the ACE/TAO version being used.
-  Specifically, double check that the ACE and TAO versions listed in ``README.md`` match the versions in the configure script.
 - Document changes to building OpenDDS, at least in :doc:`/devguide/building/index`, but possibly also in :ghfile:`java/README` and :ghfile:`java/INSTALL`.
 
 Update the Modeling SDK version numbers and release notes
@@ -160,6 +158,11 @@ Before Running the Release Script
     - `You have uploaded your SSH public key to your GitHub account <https://help.github.com/articles/generating-an-ssh-key>`__
     - `You have created a Personal Access Token for your GitHub account <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__
 
+  - You are a maintainer on the `OpenDDS Read the Docs project <https://readthedocs.org/projects/opendds/>`__.
+
+    - Maintainers can add new maintainers `here <https://readthedocs.org/dashboard/opendds/users/>`__.
+    - You will need a `API token <https://readthedocs.org/accounts/tokens/>`__.
+
   - The following `Perl CPAN modules <http://www.cpan.org/modules/INSTALL.html>`__ are required (`Perl core modules <https://perldoc.perl.org/modules>`__ should not be listed here):
 
     - `Pithub <https://metacpan.org/pod/Pithub>`__
@@ -187,11 +190,13 @@ Before Running the Release Script
 
   For micro releases, check out the relevant branch that the release will come from and pass ``--branch=BRANCH`` along with the ``--micro`` argument.
 
-- Export a ``GITHUB_TOKEN`` Bash shell variable with your `GitHub Personal Access Token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__ as shown below:
+- Set tokens the release script needs to interact with web services by exporting them as environment variables.
+  These are ``GITHUB_TOKEN`` for your `GitHub Personal Access Token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__ and ``READ_THE_DOCS_TOKEN`` for your `Read the Docs API token <https://readthedocs.org/accounts/tokens/>`__ as shown below:
 
   .. code-block:: bash
 
       export GITHUB_TOKEN=ff00ff00ff00ff00ff00ff00ff00ff00ff00ff00
+      export READ_THE_DOCS_TOKEN=ff00ff00ff00ff00ff00ff00ff00ff00ff00ff00
 
 Running the Release Script
 ==========================

tools/scripts/gitrelease.pl

@@ -159,8 +159,7 @@ sub help {
     "Environment Variables:\n" .
     "  GITHUB_TOKEN           GitHub token with repo access to publish release on\n" .
     "                         GitHub.\n" .
-    # When this is ready also remove fixed skip on RTD step
-    # "  READ_THE_DOCS_TOKEN    Access token for Read the Docs Admin\n" .
+    "  READ_THE_DOCS_TOKEN    Access token for Read the Docs Admin\n" .
     "  SFTP_USERNAME          SFTP Username\n" .
     "  SFTP_HOST              SFTP Server Address\n" .
     "\n" .
@@ -389,8 +388,6 @@ sub compare_workspace_info {
 sub check_workspace {
   my $settings = shift();
 
-  return if $settings->{list};
-
   if (!-d $settings->{workspace}) {
     print("Creating workspace directory \"$settings->{workspace}\"\n");
     if (!make_path($settings->{workspace})) {
@@ -1743,23 +1740,19 @@ sub verify_update_readme_file {
   my $step_options = shift() // {};
   my $post_release = $step_options->{post_release} // 0;
 
-  my $link = get_rtd_link($settings, $post_release);
+  my $link = get_rtd_link($settings, !$post_release);
   my $link_re = quotemeta($link);
   my $found_link = 0;
   open(my $fh, $readme_file) or die("Can't open \"$readme_file\": $?");
   while (<$fh>) {
     if ($_ =~ /$link_re/) {
+      print STDERR ("Found $link on $readme_file:$.\n");
       $found_link = 1;
-      last;
     }
   }
   close($fh);
 
-  if (!$found_link) {
-    print("Didn't find $link\n");
-  }
-
-  return $found_link;
+  return !$found_link;
 }
 
 sub message_update_readme_file {
@@ -1770,15 +1763,12 @@ sub remedy_update_readme_file {
   my $settings = shift();
   my $post_release = shift() // 0;
 
-  my $link = quotemeta(get_rtd_link($settings, !$post_release));
+  my $link_re = quotemeta(get_rtd_link($settings, !$post_release));
   my $replace_with = get_rtd_link($settings, $post_release);
-  my $replaced_link = 0;
   open(my $fh, "+< $readme_file") or die("Can't open \"$readme_file\": $?");
   my $out = '';
   while (<$fh>) {
-    if ($_ =~ s/$link/$replace_with/) {
-      $replaced_link = 1;
-    }
+    $_ =~ s/$link_re/$replace_with/g;
     $out .= $_;
   }
 
@@ -1787,7 +1777,7 @@ sub remedy_update_readme_file {
   truncate($fh, tell($fh)) or die("Truncating: $!");
   close($fh) or die("Closing: $!");
 
-  return $replaced_link;
+  return 1;
 }
 
 ############################################################################
@@ -2718,7 +2708,8 @@ sub verify_rtd_activate {
     $settings, 'GET',
     res_json_ref => \$version_info,
   ));
-  return $version_info->{active} && !$version_info->{hidden};
+  return $version_info->{active} && !$version_info->{hidden} &&
+    $version_info->{privacy_level} eq 'public';
 }
 
 sub message_rtd_activate {
@@ -2734,6 +2725,7 @@ sub remedy_rtd_activate {
     req_json_ref => {
       active => $JSON::PP::true,
       hidden => $JSON::PP::false,
+      privacy_level => 'public',
     },
     expect_status => 204,
   ));
@@ -3291,7 +3283,6 @@ sub remedy_release_occurred_flag {
     remedy => sub{remedy_rtd_activate(@_)},
     post_release => 1,
     can_force => 1,
-    skip => 1, # When this is ready, also uncomment READ_THE_DOCS_TOKEN in help
   },
   {
     name => 'Trigger Shapes Demo Build',