docs: set up for release documentation.

Make changes to publish security.html with CVE announcements referring
to the sections in upgrading.html rather than CVE.html.

Remove templates.zip as part of html build in Makefile.

Also update doc for using CVE.html.

Author: rouilj

doc/CVE.txt

@@ -2,21 +2,26 @@
    This file is a temporary way to post CVE notifications before
    a release.
 
-   Document the CVE fix info in upgrading.txt. Publishing
-   upgrading.txt would push info on the next release not the current
-   release.
+   Document the CVE fix info in upgrading.txt. We extract the sections
+   from upgrading.txt that deal with the CVE into a separate CVE.html.
+   An updated docs/security.html and docs/CVE.html provide the details
+   on a between release CVE announcment.
 
-   So we comment out a reference anchor in upgrading.txt and use that
-   comment to extract the section from upgrading.txt into CVE.txt.
-   The extracted section gets the same anchor that is in upgrading.txt,
-   but is is not commented out.
+   Publishing upgrading.txt would include info on the to be released
+   roundup software and wouldn't match the rest of the release docs.
 
-   Then we add a summary to the list of CVE's in security.txt using a
-   :ref: to the anchor. If CVE.txt is part of the build and
-   upgrading.txt has a commented out anchor, security.txt entries link
-   to CVE.html in the generated documentation.
+   To extract the info from upgrading.txt to use in CVE.html, add a
+   commented out a reference anchor in upgrading.txt. Then in CVE.txt
+   we use an include directive with start-after and end-before options
+   to exract the sections from upgrading.txt into CVE.html.
 
-   In upgrading.txt add a
+   The extracted section in CVE.txt gets the same anchor that is in
+   upgrading.txt, but is is not commented out. This allows us to swap
+   out CVE.txt and uncomment the reference in upgrading.txt. Then
+   rerunning sphinx-build will make security.html point to the sections
+   in upgrading.html.
+
+   For example, in upgrading.txt add a
 
    .. comment: _CVE-2024-39124:
 
@@ -44,14 +49,17 @@
       :end-before: .. comment: end of CVE
 
    After building the docs, install docs/security.html and
-   docs/CVE.html on the web site. Use the security.html URL
-   on the web site to update the CVE report.
+   docs/CVE.html on the web site. Reference:
+
+       https://www.roundup-tracker.org/docs/security.html
+   
+   in the CVE announcement from Mitre.
 
    When the release is ready, replace 'comment: _CVE' with '_CVE' in
    upgrading.txt. This makes the anchors in upgrading.txt live.
 
-    Then disable CVE.txt by removing CVE.txt from contents.txt in the
-   toctree hidden section. Also add CVE.txt to exclude_patterns in
+   Then disable CVE.txt by removing CVE.txt from contents.txt in the
+   toctree hidden section. Also add docs/CVE.txt to exclude_patterns in
    conf.py.
 
    No change needs to happen to security.txt as it's using a :ref: and

doc/upgrading.txt

@@ -122,7 +122,7 @@ This will insert the bad API login rate limiting settings.
 Also if you have ``html_version`` set to ``xhtml``, you will get
 an error.
 
-.. comment: _CVE-2024-39124:
+.. _CVE-2024-39124:
 
 Fix for CVE-2024-39124 in help/calendar popups (recommended)
 ------------------------------------------------------------
@@ -314,7 +314,7 @@ section. These fixes are already present in 2.4.0.
 This section is for people who can not upgrade yet, and want
 to fix the issues.
 
-.. comment: _CVE-2024-39125:
+.. _CVE-2024-39125:
 
 Referer value not escaped CVE-2024-39125
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -342,7 +342,7 @@ to::
 This escapes the Referer value an prevents it from being
 executed.
 
-.. comment: _CVE-2024-39126:
+.. _CVE-2024-39126:
 
 Stop JavaScript execution from attached files CVE-2024-39126
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

website/www/Makefile

@@ -24,7 +24,7 @@ docs:
 # after upgrade to sphinx 1.8.5, search.html is missing load of searchtools.
 # fix that in postprocess
 # also sed index.html to properly format meta og:... entries.
-html: docs templates.zip
+html: docs
 	rm -rf html
 	mkdir -p $(TMP)/doctrees $(HTML)
 	sphinx-build -n -W -b html -d $(TMP)/doctrees . $(HTML)

website/www/conf.py

@@ -101,6 +101,7 @@
                     'robots.txt',
                     'docs/tracker_config.txt',
                     'COPYING.txt',
+                    'docs/CVE.txt',
                     '_tmp']
 
 # The reST default role (used for this markup: `text`) to use for all documents.

website/www/contents.txt

@@ -23,4 +23,3 @@ Contents:
    :hidden:
 
    docs/announcement
-   docs/CVE