Rearrange docs to make the content more discoverable for newcomers

[sabine]

before	after

Improve Documentation Structure and Navigation

This PR restructures the Dune documentation to make it more intuitive and easier to navigate, following better information architecture principles.

Changes

Documentation Reorganization:

1. Renamed files for clarity:

   • usage.rst → command-line-interface.rst - More descriptive title that clearly indicates the content
   • quick-start.rst → practical-examples.rst - Better reflects the actual content
   • Updated headers from "Quickstart" to "Practical Examples" and "Command-Line Interface" to "How to Use Dune's Command-Line Interface"

2. Created new core-concepts directory:

   • Moved explanation/mental-model.rst → core-concepts/mental-model.rst
   • Moved explanation/scopes.rst → core-concepts/scopes.rst
   • Added new core-concepts/terminology.rst with comprehensive glossary of Dune terms (I have no idea why this was in overview.rst)
   • Added new core-concepts/index.rst as a landing page
   • Why I think this works: This captures the most important concepts and terms for beginners and wraps them up in their own section

3. Flattened tutorial structure:

   • Moved tutorials/developing-with-dune/* → first-steps-with-dune/* (8 files)
   • Moved tutorials/dune-package-management/* → dune-package-management/* (5 files)
   • Why I believe this is useful: It makes it much easier to discover the "Getting Started" type of tutorials.

4. Added URL redirects to preserve backlinks:

   • Added sphinx-reredirects dependency to handle URL redirects
   • Configured redirects in conf.py to maintain backward compatibility for all renamed/moved pages
   • Ensures existing links to old documentation paths continue to work

5. Rearranged main table of contents to have a progression of content for newcomers

Motivation

The previous documentation structure had several issues:

• Generic names like "Developing with Dune" and "Quickstart" didn't clearly give an idea of the content and intended audience (Quickstart is a collection of examples, that enable more experienced devs to learn by imitation)
• The explanation/ directory was ambiguous in purpose (covering both basic ideas that beginners would benefit from understanding, as well as ideas that are more relevant to contributors to the Dune project)
• The tutorials/ hierarchy added unnecessary nesting (which made it difficult to see the most important tutorials right away, requiring people to click into tutorials to get started)

Follow-Up Tasks

• create more guides on Dune Package Management
  • "Using Dune Package Management in CI" (how to (e.g.) do caching in a GitHub Action the way we do with opam (cp the *.opam files into a container, then the source))
  • "Migrating from Opam to Dune Package Management"
  • "Distributing an Application with Dune Package Management"

[Alizter]

One side-effect of flattening doc/tutorials is that this directory was marked as a data_only_dirs, meaning that dune would not look at dune or dune-project in that directory. Now that they have been flattened, dune is discovering those projects. We will need to mark them each separately as data_only_dirs if we are to proceed this way.

[sabine]

I also noticed that re-running make doc doesn't build everything affected when I make changes to the table of contents. Probably the sidebar dependency isn't listed accurately? Not even sure it's possible to do reliably do that, without having to maintain the list of files the sidebar is compiled from.

[maiste]

I would advise against moving the tutorials to top level. One of the problems of the current dune documentation is that it is partially moved to a structure reflecting the diataxis framework. It is in a transient state where some pages have been reworked, but some are not...

Part of the doc are not clearly separated. Moving the tutorial top level increase this unclear separation of purposes and goes against the framework we were trying to follow to make the doc better (at least when it was improved by @ emillon)...

For the separation, I would say that "How to use Dune's Command Line Interface" should be rewritten and moved to tutorial. "First Step with Dune" should also go to tutorials/. "Package Management With Dune" should go back to tutorial.

My point is that if you want to know how to do things, the reflex is to go to tutorials. Of course, it should be linked from the first page to make it clear about the intention.

---

Also, the "FAQ" could be extracted from "Miscellaneous" to make it more visible (in general, the "Miscellaneous" top level should disappear).

The renaming makes it definitely clearer about the initiative 👌🏻

The fact that the overview is the first page when you arrive definitely makes it clearer 👍🏻

[sabine]

One of the problems of the current dune documentation is that it is partially moved to a structure reflecting the diataxis framework

Moving the most important getting started kind of documentation into a visible place on the sidebar is not at odds with diataxis. Diataxis doesn't mean to impose that the information architecture (table of contents) must squeeze documents into those four rigid buckets - all that diataxis suggests is that it is good to have a clear understanding of what type of document one is writing, and to stick to the principles of that category of document (within that document).

When surveying people for the OCaml.org documentation area revamp, we asked for pages with great documentation and a major pattern we found across all these was that documentation was structured from top to bottom in increasing order of difficulty, placing the most important and useful concepts first.

"How to use Dune's Command Line Interface" should be rewritten

Yes, that would be great, however, I think it's not a priority to rewrite anything right now. The PR only attempts to grab the lowest-hanging fruit in terms of the experience of a complete newcomer arriving on the docs having a higher chance to find the content that helps them get started.

"FAQ" could be extracted from "Miscellaneous" to make it more visible

Agreed.

[Alizter]

I think rst (make doc) will complain about non-matching underlines.