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

[aishling-scilifelab]

• Update GitHub Action to do the same for this as is done for the Technical Overview. Built PDF is called dds-troubleshooting.pdf.
• Update troubleshooting.html to have the correct path and no option to view on GitHub.
• Delete Troubleshooting.pdf
• Add troubleshooting.md
• Update link to troubleshooting doc in README
• Update Makefile

2. Jira task / GitHub issue

Link to the github issue or add the Jira task ID here.

3. Type of change

What type of change(s) does the PR contain?

Check the relevant boxes below. For an explanation of the different sections, enter edit mode of this PR description template.

• New feature
  • Breaking: Why / How? Add info here.
  • Non-breaking
• Database change: Remember the to include a new migration version, or explain here why it's not needed.
• Bug fix
• Security Alert fix
  • Package update
    • Major version update
• Documentation
• Workflow
• Tests only

4. Additional information

• Sprintlog
• Blocking PRs
  • Merged
• PR to master branch: _If checked, read the release instructions
  • I have followed steps 1-8.

5. Actions / Scans

Check the boxes when the specified checks have passed.

For information on what the different checks do and how to fix it if they're failing, enter edit mode of this description or go to the PR template.

• Black

• Prettier

• Yamllint

• Tests

• CodeQL

• Trivy

• Snyk

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.46%. Comparing base (05527d8) to head (992fc91).
Report is 7 commits behind head on dev.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev    #1546   +/-   ##
=======================================
  Coverage   92.46%   92.46%           
=======================================
  Files          29       29           
  Lines        4830     4830           
=======================================
  Hits         4466     4466           
  Misses        364      364           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[aishling-scilifelab]

Something that is a note and I possibly should do in a separate branch is that when you are developing locally, you now need to run the make command to build the PDFs. Possibly should do that in the docker compose instead.

[rv0lt]

For the workflows file:

• Name of the job is still build_tech_overview even thought it now handles the troubleshooting as well.

• Couldn't it, maybe, be a bit cleaner having it in two separate jobs? i.e keep the build_tech_overview and have a new one build_trouble ?

In adition to this last sugestion, it is also probably better to handle them as two separate artifacts. I don't find the documentation very clear to this use case of using multiple paths:
https://github.com/actions/upload-artifact?tab=readme-ov-file#upload-using-multiple-paths-and-exclusions

If multiple paths are provided as input, the least common ancestor of all the search paths will be used as the root directory of the artifact. Exclude paths do not affect the directory structure.

[valyo]

I needed to install the full MacTeX package plus librsvg (maybe we can add it to the brew install command in line 8 of Makefile) in order to successfully run the make command
Apart from that, I agree with Alvaro's comment about having separate jobs

[aishling-scilifelab]

In adition to this last sugestion, it is also probably better to handle them as two separate artifacts. I don't find the documentation very clear to this use case of using multiple paths: https://github.com/actions/upload-artifact?tab=readme-ov-file#upload-using-multiple-paths-and-exclusions

If multiple paths are provided as input, the least common ancestor of all the search paths will be used as the root directory of the artifact. Exclude paths do not affect the directory structure.

Sounds good, I was on the fence about separating but will do.

[aishling-scilifelab]

@valyo - will tidy up the commits here before merging but do the actual post-code review changes look good to you?

[aishling-scilifelab]

@rv0lt - did your requested changes - can you approve?