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.