docs: address warnings in docs builds

[terriko]

While I was reviewing some of the version bump PRs related to doc/requirements.txt I noticed that our current docs build says it's got 10 warnings. It's been a while since we looked at those so I'm filing this issue as a reminder that we should look at the warnings, see what they recommend, and resolve them.

Some of them are probably pretty straightforward to fix and others are going to be more complicated because they look like lexical parser errors. If you intend to work on this, I'd recommend doing easy stuff first and in a separate PR so they can be merged easily, and leaving the more complicated ones in separate PRs.

You can get the list of warnings locally by going into the doc/ directory and running make html but here's the logs:

2024-04-23T16:26:58.6091095Z Running Sphinx v7.3.7
2024-04-23T16:26:59.4311516Z making output directory... done
2024-04-23T16:26:59.4427063Z myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=6, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
2024-04-23T16:26:59.4432585Z building [mo]: targets for 0 po files that are out of date
2024-04-23T16:26:59.4433724Z writing output... 
2024-04-23T16:26:59.4434762Z building [html]: targets for 22 source files that are out of date
2024-04-23T16:26:59.4444889Z updating environment: [new config] 22 added, 0 changed, 0 removed
2024-04-23T16:26:59.4446655Z reading sources... [  5%] CHECKERS
2024-04-23T16:26:59.5328909Z reading sources... [  9%] CONTRIBUTING
2024-04-23T16:26:59.6027995Z reading sources... [ 14%] CSV2CVE
2024-04-23T16:26:59.6092809Z reading sources... [ 18%] MANUAL
2024-04-23T16:26:59.8176275Z reading sources... [ 23%] README
2024-04-23T16:26:59.9183832Z reading sources... [ 27%] RELEASE
2024-04-23T16:26:59.9638288Z reading sources... [ 32%] how_to_guides/customize_html_report
2024-04-23T16:26:59.9960390Z reading sources... [ 36%] how_to_guides/cve_scanner_gh_action
2024-04-23T16:27:00.0026026Z reading sources... [ 41%] how_to_guides/filter_intermediate_reports
2024-04-23T16:27:00.0075264Z reading sources... [ 45%] how_to_guides/index
2024-04-23T16:27:00.0293545Z reading sources... [ 50%] how_to_guides/multiple_scans_at_once
2024-04-23T16:27:00.0337848Z reading sources... [ 55%] how_to_guides/offline
2024-04-23T16:27:00.0405960Z reading sources... [ 59%] how_to_guides/sbom
2024-04-23T16:27:00.0507250Z reading sources... [ 64%] how_to_guides/sbom_generation
2024-04-23T16:27:00.0577753Z reading sources... [ 68%] how_to_guides/scan_docker_image
2024-04-23T16:27:00.0707372Z reading sources... [ 73%] how_to_guides/scan_installed_packages
2024-04-23T16:27:00.0750310Z reading sources... [ 77%] how_to_guides/use_incremental_updates
2024-04-23T16:27:00.0806082Z reading sources... [ 82%] how_to_guides/use_intermediate_reports
2024-04-23T16:27:00.0897359Z reading sources... [ 86%] index
2024-04-23T16:27:00.0955085Z reading sources... [ 91%] new-contributor-tips
2024-04-23T16:27:00.1337428Z reading sources... [ 95%] pypi_downloads
2024-04-23T16:27:00.1382763Z reading sources... [100%] sboms_for_humans/README
2024-04-23T16:27:00.1424533Z 
2024-04-23T16:27:00.1427645Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/customize_html_report.md:102: ERROR: Document or section may not begin with a transition.
2024-04-23T16:27:00.1430835Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/customize_html_report.md:182: ERROR: Document or section may not begin with a transition.
2024-04-23T16:27:00.1433905Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/customize_html_report.md:291: ERROR: Document or section may not begin with a transition.
2024-04-23T16:27:00.1436807Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/customize_html_report.md:376: ERROR: Document or section may not begin with a transition.
2024-04-23T16:27:00.1438655Z looking for now-outdated files... none found
2024-04-23T16:27:00.1672494Z pickling environment... done
2024-04-23T16:27:00.1673529Z checking consistency... done
2024-04-23T16:27:00.1686579Z preparing documents... done
2024-04-23T16:27:00.2088123Z copying assets... copying static files... done
2024-04-23T16:27:00.2089217Z copying extra files... done
2024-04-23T16:27:00.2090280Z done
2024-04-23T16:27:00.2092102Z writing output... [  5%] CHECKERS
2024-04-23T16:27:00.3460516Z writing output... [  9%] CONTRIBUTING
2024-04-23T16:27:00.4065615Z writing output... [ 14%] CSV2CVE
2024-04-23T16:27:00.4207891Z writing output... [ 18%] MANUAL
2024-04-23T16:27:00.5628703Z writing output... [ 23%] README
2024-04-23T16:27:00.6298268Z writing output... [ 27%] RELEASE
2024-04-23T16:27:00.6670084Z writing output... [ 32%] how_to_guides/customize_html_report
2024-04-23T16:27:00.7592895Z writing output... [ 36%] how_to_guides/cve_scanner_gh_action
2024-04-23T16:27:00.7763269Z writing output... [ 41%] how_to_guides/filter_intermediate_reports
2024-04-23T16:27:00.7874276Z writing output... [ 45%] how_to_guides/index
2024-04-23T16:27:00.7989435Z writing output... [ 50%] how_to_guides/multiple_scans_at_once
2024-04-23T16:27:00.8091091Z writing output... [ 55%] how_to_guides/offline
2024-04-23T16:27:00.8204358Z writing output... [ 59%] how_to_guides/sbom
2024-04-23T16:27:00.8341302Z writing output... [ 64%] how_to_guides/sbom_generation
2024-04-23T16:27:00.8458395Z writing output... [ 68%] how_to_guides/scan_docker_image
2024-04-23T16:27:00.8629241Z writing output... [ 73%] how_to_guides/scan_installed_packages
2024-04-23T16:27:00.8704342Z writing output... [ 77%] how_to_guides/use_incremental_updates
2024-04-23T16:27:00.8807821Z writing output... [ 82%] how_to_guides/use_intermediate_reports
2024-04-23T16:27:00.8967543Z writing output... [ 86%] index
2024-04-23T16:27:00.9548742Z writing output... [ 91%] new-contributor-tips
2024-04-23T16:27:00.9631280Z writing output... [ 95%] pypi_downloads
2024-04-23T16:27:00.9703114Z writing output... [100%] sboms_for_humans/README
2024-04-23T16:27:00.9760558Z 
2024-04-23T16:27:00.9764785Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/MANUAL.md:520: WARNING: Unknown source document '../cve_bin_tool/parsers/README' [myst.xref_missing]
2024-04-23T16:27:00.9766834Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/MANUAL.md:522: WARNING: Unknown source document '../cve_bin_tool/checkers/README' [myst.xref_missing]
2024-04-23T16:27:00.9768519Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/MANUAL.md:1071: WARNING: Pygments lexer name 'csv' is not known
2024-04-23T16:27:00.9782478Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/customize_html_report.md:446: WARNING: Lexing literal_block '\n<!DOCTYPE  html>\n\n<html  lang="en">\n<head>\n\t<meta  charset="UTF-8">\n\t<meta  name="viewport"\n\t\tcontent="width=device-width, initial-scale=1.0, user-scalable=0,shrink-to-fit=no, maximum-scale=1, minimum-scale=1">\n\t<title>CVE-BIN-TOOL | Descriptive Report</title>\n\n\t<!-- JavaScript for Plotly -->\n\t<script> {{ script_plotly }}</script>\n\t<!-- Bootstrap CSS -->\n\t<style>\n\t\t/* Bootstrap */\n\t\t{{ style_bootstrap }}\n\t\t/* Mystylesheet */\n\t\t{{ style_main }}\n\t</style>\n</head>\n<body>\n\t<div  class="container-fluid">\n\t<!-- Name of the tool and Date at which is generated -->\n\t\t<div  class="card bg-title text-light m-t-20 m-b-20">\n\t\t\t<div  class="card-header">\n\t\t\t\t<div  class="row justify-content-sm-centre ">\n\t\t\t\t\t<!-- Name of the Tool -->\n\t\t\t\t\t<div  class="col-sm-auto col-sm ">\n\t\t\t\t\t\t<h4  class="font-weight-light">CVE Binary Tool: Descriptive Report</h4>\n\t\t\t\t\t</div>\n\t\t\t\t\t<!-- Report generation date -->\n\t\t\t\t\t<div  class="col-sm">\n\t\t\t\t\t\t<h4  class="text-right font-weight-light"> {{ date }}</h4>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</div>\n\t\t<!-- Block for Dashboard -->\n\t\t{{ dashboard }}\n\n\t\t<!-- Header All Products -->\n\t\t<div  class="card bg-title text-light m-t-20 m-b-15">\n\t\t\t<div  class="card-header">\n\t\t\t\t<div  class="row">\n\t\t\t\t\t<div  class="col-9">\n\t\t\t\t\t\t<h5  class="font-weight-light p-t-5">Products With Known Vulnerability</h5>\n\t\t\t\t\t</div>\n\t\t\t\t\t<div  class="col-3 text-right">\n\t\t\t\t\t\t<button  class="btn btn-filter borderButton text-color-main"  data-toggle="collapse" data-target="#filterdiv">Search Data</button>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</div>\n\t\t<div  class="row collapse text-center"  id="filterdiv">\n\t\t\t<div  class="offset-4 col-4 onset-4">\n\t\t\t\t<div  class="active-pink-4 mb-4">\n\t\t\t\t\t<input  id="searchInput"  class="form-control"  type="text"  placeholder="Search"  aria-label="Search">\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</div>\n\t\t<!-- List of all the products -->\n\t\t<div  id="listProducts">\n\t\t\t{{ products_found }}\n\t\t</div>\n\t</div>\n\t<!-- Jquery -->\n\t<script>{{ script_jquery }}</script>\n\t<!-- Bootstrap JS -->\n\t<script>{{ script_bootstrap }}</script>\n\t<script>\n\t\t{{ script_main }}\n\t</script>\n</body>\n</html>\n' as "html" resulted in an error at token: '{'. Retrying in relaxed mode.
2024-04-23T16:27:00.9794403Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/cve_scanner_gh_action.md:13: WARNING: Pygments lexer name 'yml' is not known
2024-04-23T16:27:00.9798342Z /home/runner/work/cve-bin-tool/cve-bin-tool/doc/how_to_guides/use_intermediate_reports.md:23: WARNING: Lexing literal_block '{\n    "metadata": {\n        "timestamp": "2021-06-17.00-00-30",\n        "tag": "",\n        "scanned_dir": "/home/code/backend",\n        "products_with_cve": 139,\n        "products_without_cve": 2,\n        "total_files": 49\n    },\n    "report": [\n        {\n            "vendor": "gnu",\n            "product": "gcc",\n            "version": "9.0.1",\n            "cve_number": "CVE-2019-15847",\n            "severity": "HIGH",\n            "score": "7.5",\n            "cvss_version": "3",\n            "paths": "/home/code/backend/glib.tar.gz,/home/code/backend/gcc.tar.gz",\n            "remarks": "NewFound",\n            "comments": ""\n        },\n        ...\n    ]\n}\n' as "json" resulted in an error at token: '.'. Retrying in relaxed mode.
2024-04-23T16:27:00.9878872Z generating indices... genindex done
2024-04-23T16:27:00.9945357Z writing additional pages... search done
2024-04-23T16:27:00.9948666Z copying images... [  8%] images/cve-bin-tool-database.png
2024-04-23T16:27:00.9953281Z copying images... [ 17%] images/metric/console_table.png
2024-04-23T16:27:00.9958597Z copying images... [ 25%] images/metric/metric_table.png
2024-04-23T16:27:00.9963753Z copying images... [ 33%] images/metric/HTML.png
2024-04-23T16:27:00.9973841Z copying images... [ 42%] images/metric/PDF.png
2024-04-23T16:27:00.9979131Z copying images... [ 50%] images/metric/CSV.png
2024-04-23T16:27:00.9985704Z copying images... [ 58%] images/metric/JSON.png
2024-04-23T16:27:00.9991059Z copying images... [ 67%] images/html_preview.png
2024-04-23T16:27:00.9996113Z copying images... [ 75%] images/html_highlight.png
2024-04-23T16:27:01.0000682Z copying images... [ 83%] images/html_filter.png
2024-04-23T16:27:01.0005087Z copying images... [ 92%] map1.png
2024-04-23T16:27:01.0013089Z copying images... [100%] map2.png
2024-04-23T16:27:01.0017012Z 
2024-04-23T16:27:01.0089470Z dumping search index in English (code: en)... done
2024-04-23T16:27:01.0093894Z dumping object inventory... done
2024-04-23T16:27:01.0094651Z build succeeded, 10 warnings.