Docs aren't building due to sphinx / jinja2 error

[terriko]

Looks like we got hit with an issue in sphinx / jinja2

sphinx-doc/sphinx#10291

We're currently pinned to an older version of Sphinx. Pinning versions is explicitly recommended by ReadTheDocs to improve the stability of their builds, so we'll still want to pin something that we know works:

/~https://github.com/intel/cve-bin-tool/blob/main/doc/requirements.txt

Recommended solution is to upgrade to Sphinx 4.0.2, temporary work around seems to be to pin jinja2 to an earlier version. As long as the docs don't break with the newer version of Sphinx, that would be my preferred solution. Anyone fixing this will need to update the version of Sphinx in the file above (doc/requirements.txt) then build the docs using that version and if they build without issue, look at the resulting docs (use make, particularly make html in the docs/ directory) to make sure they look ok (look particularly at the checker tables, as those are probably most likely to break). If they don't look ok, make any necessary changes to bring them in compliance with the newer versions required.

This is probably a 1 line change + some time confirming that everything is fine, so I'll leave it flagged as a "good first issue"

[Alienmaster]

I build the docs with sphinx-build -b html . _build with version 4.0.2 and besides one warning it worked:

$ sphinx-build -b html . _build
Running Sphinx v4.0.2
WARNING: html_static_path entry '_static' does not exist
loading pickled environment... done
myst v0.17.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=[], 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', disable_syntax=[], all_links_external=False, url_schemes=['http', 'https', 'mailto', 'ftp'], ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=6, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded, 1 warning.

The HTML pages are in _build.

If i change the conf.py and comment html_static_path = ["_static"] out it works. without a warning.

$ sphinx-build -b html . _build
Running Sphinx v4.0.2
loading pickled environment... done
myst v0.17.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=[], 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', disable_syntax=[], all_links_external=False, url_schemes=['http', 'https', 'mailto', 'ftp'], ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=6, heading_slug_func=None, html_meta=[], footnote_transition=True, substitutions=[], sub_delimiters=['{', '}'], words_per_minute=200)
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in _build.

Is there a reason for the parameter? I get the same error with make doc and make html

The tables for example in readme.html look a bit different compared to the online version (Screenshots from Chrome 99 x64 Win10):
Sphinx 4.0.2:

Online Version from readthedocs:

I made the screenshots with a bit of text to compare the new width of both tables.

[terriko]

Huh, I'm not sure why _static was configured like that either. Maybe it was part of the original auto-generated file? Or maybe we were using it before things got rearranged? Go ahead and make a pull request removing _static and changing Sphinx to 4.0.2 and we should be good to close this bug, then. Thank you for investigating!