DDS-2033: Store troubleshooting doc as markdown, delete PDF

.github/workflows/docker-compose-tests.yml

@@ -22,7 +22,7 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Run tests against database container
-        run: docker-compose -f docker-compose.yml -f tests/docker-compose-test.yml up --build --exit-code-from backend
+        run: docker compose -f docker-compose.yml -f tests/docker-compose-test.yml up --build --exit-code-from backend
 
       - name: Setup upterm session
         uses: lhotari/action-upterm@v1

.github/workflows/publish_and_trivyscan.yml

@@ -24,12 +24,13 @@ on:
     types: [published]
 jobs:
   build_tech_overview:
-    name: Build Technical Overview
+    name: Build technical overview
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repo
         uses: actions/checkout@v4
-      - uses: docker://pandoc/latex:3.2
+      - name: Build tech overview PDF
+        uses: docker://pandoc/latex:3.2
         with:
           entrypoint: /bin/sh
           args: >-
@@ -39,14 +40,39 @@ jobs:
             updmap-sys &&
             pandoc
             --output=dds_web/static/dds-technical-overview.pdf
-            doc/technical-overview.md"
-      - name: Upload PDF artifact
+            doc/technical-overview.md
+            "
+      - name: Upload technical overview PDF
         uses: actions/upload-artifact@v4
         with:
-          name: tech-overview-pdf
+          name: technical-overview-pdf
           path: dds_web/static/dds-technical-overview.pdf
+  build_troubleshooting:
+    name: Build troubleshooting guide
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+      - name: Build troubleshooting guide
+        uses: docker://pandoc/latex:3.2
+        with:
+          entrypoint: /bin/sh
+          args: >-
+            -c "
+            tlmgr update --self &&
+            tlmgr install cm-super fontaxes lato xkeyval &&
+            updmap-sys &&
+            pandoc
+            --output=dds_web/static/dds-troubleshooting.pdf
+            doc/troubleshooting.md
+            "
+      - name: Upload troubleshooting PDF
+        uses: actions/upload-artifact@v4
+        with:
+          name: troubleshooting-pdf
+          path: dds_web/static/dds-troubleshooting.pdf
   push_to_registry:
-    needs: build_tech_overview
+    needs: [build_tech_overview, build_troubleshooting]
     if: github.repository == 'ScilifelabDataCentre/dds_web'
     name: Push image
     runs-on: ubuntu-latest
@@ -66,11 +92,16 @@ jobs:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Download Tech Overview artifact
+      - name: Download technical overview PDF
+        uses: actions/download-artifact@v4
+        with:
+          name: technical-overview-pdf
+          path: dds_web/static/dds-technical-overview.pdf
+      - name: Download troubleshooting PDF
         uses: actions/download-artifact@v4
         with:
-          name: tech-overview-pdf
-          path: dds_web/static
+          name: troubleshooting-pdf
+          path: dds_web/static/dds-troubleshooting.pdf
       - name: Docker metadata
         id: meta
         uses: docker/metadata-action@v5

Makefile

@@ -1,15 +1,22 @@
 # For Linux and MacOS users only and assumes brew is already installed
 TECH_MARKDOWN_FILE := doc/technical-overview.md
-PDF_OUTFILE := dds_web/static/dds-technical-overview.pdf
+TECH_OVERVIEW_PDF := dds_web/static/dds-technical-overview.pdf
+TROUBLE_MARKDOWN_FILE := doc/troubleshooting.md
+TROUBLE_PDF := dds_web/static/dds-troubleshooting.pdf
 
 install_pandoc:
-	brew install pandoc
+	brew install pandoc basictex librsvg
 
 update_tlmgr:
 	tlmgr update --self
 	tlmgr install cm-super fontaxes lato pdflscape xkeyval
 
 build_tech_overview_pdf: update_tlmgr $(TECH_MARKDOWN_FILE)
-	pandoc $(TECH_MARKDOWN_FILE) -o $(PDF_OUTFILE)
+	pandoc $(TECH_MARKDOWN_FILE) -o $(TECH_OVERVIEW_PDF)
 
-.PHONY: update_tlmgr build_tech_overview_pdf all
+build_troubleshooting_pdf: update_tlmgr $(TROUBLE_MARKDOWN_FILE)
+	pandoc $(TROUBLE_MARKDOWN_FILE) -o $(TROUBLE_PDF)
+
+build_docs: build_tech_overview_pdf build_troubleshooting_pdf
+
+.PHONY: update_tlmgr build_tech_overview_pdf build_troubleshooting_pdf build_docs all

README.md

@@ -37,7 +37,7 @@
    <a href="https://github.com/ScilifelabDataCentre/dds_web/wiki/Architecture-Decision-Record,-ADR">
       <img alt="Architecture Decision Record" src="https://img.shields.io/badge/-ADR-000000?logo=github">
    </a>
-   <a href="https://github.com/ScilifelabDataCentre/dds_web/blob/master/doc/Troubleshooting.pdf">
+   <a href="https://github.com/ScilifelabDataCentre/dds_web/blob/master/doc/troubleshooting.md">
       <img alt="Troubleshooting" src="https://img.shields.io/badge/-Troubleshooting%20Guide-red?logo=github">
    </a>
    <a href="https://github.com/ScilifelabDataCentre/dds_cli">

SPRINTLOG.md

@@ -412,3 +412,7 @@ _Nothing merged in CLI during this sprint_
 - Build Technical Overview PDF in GitHub Actions, rename to include DDS and remove option to view on GitHub ([#1541](https://github.com/ScilifelabDataCentre/dds_web/pull/1541/))
 - Fixed index out of range when listing files from root ([#1543](https://github.com/ScilifelabDataCentre/dds_web/pull/1543/))
 - Update Trivy GitHub Actions ([#1545](https://github.com/ScilifelabDataCentre/dds_web/pull/1545))
+
+# 2024-07-29 - 2024-08-09
+
+- Move raw troubleshooting doc to repo and make small updates ([#1546](https://github.com/ScilifelabDataCentre/dds_web/pull/1546))

dds_web/templates/troubleshooting.html

@@ -5,8 +5,7 @@ <h2>Troubleshooting the DDS</h2>
     </br>
     <h4>Experiencing issues with the DDS?</h4>
     <p>Please <strong>read the troubleshooting document</strong> which provides answers to previously asked questions and possible solutions to issues that have been reported. </p>
-    <p>The document can be found on GitHub or downloaded as a PDF.</p> 
-    <p class="lead"><a class="btn btn-info" href="https://github.com/ScilifelabDataCentre/dds_web/blob/master/doc/Troubleshooting.pdf" target="_blank">Read on GitHub</a>&nbsp;<a class="btn btn-info" href="https://github.com/ScilifelabDataCentre/dds_web/raw/master/doc/Troubleshooting.pdf">Download the PDF</a>&nbsp;</p>
+    <p class="lead"><a class="btn btn-info" href="/static/dds-troubleshooting.pdf">Download the PDF</a>&nbsp;</p>
     <br>
     <h4>Did the troubleshooting document not help?</h4>
     <p>Please <strong>go through the following steps</strong>:</p>
@@ -16,8 +15,8 @@ <h4>Did the troubleshooting document not help?</h4>
         <li><strong>Read</strong> through the sections in the <a href="https://delivery.scilifelab.se/technical">technical overview</a> relevant to your issue and check the topics below for possible solutions.</li>
     </ol>
     <br>
-    <h4>Does the issue persist and / or the provided information not help?</h4>
-    <p>If you're a <b> data producer </b>, using the DDS for data deliveries to your users: contact the 
+    <h4>Does the issue persist and/or the provided information not help?</h4>
+    <p>If you're a <b> data producer</b>, using the DDS for data deliveries to your users: contact the
     <!-- 
         email obfuscation: 
         - the address is split into parts and concatenated in the JavaScript function
@@ -42,14 +41,14 @@ <h4>Does the issue persist and / or the provided information not help?</h4>
         })();        
         // --> </script> <noscript>Data Centre.</noscript>  <!-- no JavaScript just display the text -->
     </p>
-    <p>If you're a <b> data recipient </b>, using the DDS to download your data from a data producing SciLifeLab unit: contact the SciLifeLab unit responsible for delivering the data to you.</p>
+    <p>If you're a <b> data recipient</b>, using the DDS to download your data from a data producing SciLifeLab unit: contact the SciLifeLab unit responsible for delivering the data to you.</p>
     <p>Please <strong>provide the following information</strong>:</p>
     <ul>
-        <li>Did the error / issue occurr in the web interface or the CLI?</li>
+        <li>Did the error/issue occur in the web interface or the CLI?</li>
         <li>Web:</li>
         <ul>
             <li>What did you attempt to do?</li>
-            <li>When did this message / error appear? </li>
+            <li>When did this message/error appear? </li>
             <li>Screenshot of the web page with the error.</li>
         </ul>
         <li>CLI</li>