docs: Reorg and improve user experience

[tsteenbe]

Reorganize and improve documentation to provide a better getting started and documentation navigation user experience.

Included changes:

• Adoption of the Diátaxis framework which prioritizes user needs and organizes documentation accordingly. This approach ensures users can easily find the information they need while providing authors with clear guidance on improving documentation for a better user experience.
• Implement consistent file and folder naming optimized for SEO.

Closes: aboutcode-org/www.aboutcode.org/issues/39.

[tsteenbe]

Ping @DennisClark - this pull request contains the "template" for how we want apply to other AboutCode projects.

Things I at a minimum would like to see copied over to other AboutCode projects

1. Consistent table of contents layout based on the AboutCode version of Diataxis

   • Getting Started
     • Installation
     • FAQs
     • Contributing to [insert project name]
   • Tutorials
   • How-to Guides
   • Reference
   • Explanation

2. The landing page

[mjherzog]

@tsteenbe What is the plan for merging these changes. Are you waiting for @DennisClark to review the changes?
I am asking because this will be much easier to use as an example if published to SCTK RTD.

[tsteenbe]

@mjherzog I already pinged @AyanSinhaMahapatra over docs Slack to ask him to do the review of this PR. Yes having it pushed on SCTK RTD would be nice but @DennisClark can also build the docs locally using make docs.

[Copilot]

Pull request overview

This PR reorganizes and improves the ScanCode documentation by adopting the Diátaxis framework and implementing consistent file and folder naming conventions optimized for SEO. The changes enhance the user experience by making documentation easier to navigate and find, while providing clearer guidance for documentation authors.

• Renamed files and references from snake_case to kebab-case (e.g., how_to_run_a_scan.rst → running-a-scan.rst)
• Updated all internal references to use new naming conventions
• Improved heading capitalization and formatting consistency
• Enhanced code block syntax using proper directives
• Reorganized documentation structure following Diátaxis principles

Reviewed changes

Copilot reviewed 82 out of 132 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/source/tutorials/visualizing-scan-results.rst	Updated reference label and heading capitalization
docs/source/tutorials/running-a-scan.rst	Added reference label, improved headings, updated code blocks and image references
docs/source/tutorials/index.rst	Simplified heading and updated file references to kebab-case
docs/source/tutorials/configuring-scan-output-formats.rst	Updated references and improved heading consistency
docs/source/tutorials/configuring-scan-detection.rst	Updated references and converted examples to code-block directives
docs/source/tutorials/adding-a-post-scan-plugin.rst	Updated reference labels and heading capitalization
docs/source/rst-snippets/*	Created new organized snippet files with improved naming and formatting
docs/source/reference/scancode-cli/*	Created new CLI reference structure with improved organization
docs/source/reference/scancode-plugins/*	Reorganized plugin documentation with consistent naming
docs/source/reference/scancode-reindex-licenses-cli.rst	Restructured with better headings and code examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[AyanSinhaMahapatra]

Thanks @tsteenbe. I added some changes to update the docs too

[AyanSinhaMahapatra]

We don't have any explicit links to the details page for every CLI options section, apart from this being present in the sidebar, and the toctree above is also hidden.

Instead we should include the toctree in the bottom and not keep this hidden, and also refer to the details pages for every CLI options section at the end of each quick reference sections.

[AyanSinhaMahapatra]

This is not correct, neither the order nor the actual sections are identical currently, so removing for now. The CLI has some additional grouping (like basic options are further grouped in primary scans, other scans and scan options which makes sense IMHO, if we want we can also structure the doc options similarly to avoid confusion)

[AyanSinhaMahapatra]

The --classify option was moved from a pre-scan option to a post-scan option but the doc was not updated, I'm adding the update.

[AyanSinhaMahapatra]

I moved extractcode and scancode-reindex-licenses into the scancode CLI section, as these are actually part of the scancode CLI IMHO. Also added the scancode-license-data CLI command here as this was missing.

[AyanSinhaMahapatra]

Added 2 new sections which were missing and IMHO should be there:

• other CLI commands
• help/doc options