Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update Sphinx and myst-parser versions; resolve warnings #4581

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

giacob500
Copy link

@giacob500 giacob500 commented Nov 21, 2024

Summary

This PR is intended to address issue #4311 (docs: upgrading sphinx & myst-parser)

  • Updated Sphinx to version 8.0.2 and myst-parser to version 4.0.0.
  • Successfully built the documentation.
  • Encountered warnings about certain documents not being included in any toctree.

Details

While building the documentation using make docs, I received the following warnings:

checking consistency... cve-bin-tool/doc/how_to_guides/vex_generation.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/mismatch_cli.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/sboms_for_humans/cve-bin-tool-py3.10.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/sboms_for_humans/cve-bin-tool-py3.11.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/sboms_for_humans/cve-bin-tool-py3.12.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/sboms_for_humans/cve-bin-tool-py3.7.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/sboms_for_humans/cve-bin-tool-py3.8.md: WARNING: document isn't included in any toctree
cve-bin-tool/doc/sboms_for_humans/cve-bin-tool-py3.9.md: WARNING: document isn't included in any toctree

I'm unsure whether these documents should be added to the toctree or if they're intentionally excluded.

Questions

  • Should I include these documents in the toctree?
  • If so, where would be the appropriate place to include them?
  • If not, is it acceptable to suppress these warnings?

Additional Notes

  • I haven't made changes to address these warnings yet, pending your guidance.
  • Any feedback or suggestions would be greatly appreciated.

@terriko
Copy link
Contributor

terriko commented Nov 21, 2024

I think if we're bothering to generate documents, it makes more sense to include them so they're reachable, so we might as well fix all those issues. Suggestions:

  • the vex one should be included with the other how to guides
  • the mismatch one probably can also go with the how to guides for now. I'm open to other suggestions if somewhere else looks more reasonable.
  • the sbom for humans stuff should have its own toctree (and that in turn should be linked to the main toctree so people can find them if they want)

The last one is a little less important since I think people coming to look at the sboms are more likely to be browsing through git than the documentation, but who knows, maybe having that info on readthedocs will be useful to someone, and we've got a low-key goal of making sboms more accessible and usable so this seems to fit into that.

@terriko terriko changed the title Update Sphinx and myst-parser versions; resolve documentation warnings docs: Update Sphinx and myst-parser versions; resolve warnings Nov 21, 2024
Copy link
Contributor

@terriko terriko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I edited the title so it should pass the gitlint check next time the job runs (it won't update until you make changes).

It looks like spelling is complaining about 132 missing items. Since there's a lot of package and human names in there, I'd suggest we just add the whole sboms directory to the spelling exclude list, which can be found here: https://github.com/intel/cve-bin-tool/blob/main/.github/actions/spelling/excludes.txt

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants