doc: split files doc into smaller documents

[emillon]

First, apologies for the large PR, but actually it is mostly moving things around.

The "previous" situation is that we have a single dune-files.rst which contains documentation for all of our files, also including dune-project, dune-workspace, and config.

To get it organized, some pieces are extracted into doc/stanzas/* but that's just textual inclusion, it still builds a single page. Also, we rely on references (:ref:) to do deep links (for example, to link to the documentation of a stanza or a field).

What this PR does is switch to a hierarchical structure, where individual stanzas are in their own document, grouped by the file type they can be found it (concretely, there is one directory for dune stanzas, one directory for dune-project stanzas, etc). And instead of relying on references, we link to documents (:doc:) directly.

Here's how the PR is structured in terms of commits:

• for each file type (config, dune, dune-project, dune-workspace):
  • move the section of dune-files.rst to /reference/files/X/index.rst
  • split the subsections into /reference/files/X/*.rst
  • remove the references and turn them into :doc: links.
• remove dune-files.rst

We can discuss the approach, and if there are concrete remarks to do I'm happy to split the PR in smaller steps, its structure should allow it easily.

Thanks

[emillon]

The interesting part can be seen here.

[emillon]

Also in terms of follow-up, I think it makes the "dune domain" extension (extra markup in seen here for example) less important; now that each stanza is in its own document, I imagine this could just be normal headings.

[emillon]

@christinerose this PR is "just" moving text around, so editing is useful but maybe I can ask you once the restructuring work is done if that's fine with you?

[christinerose]

@christinerose this PR is "just" moving text around, so editing is useful but maybe I can ask you once the restructuring work is done if that's fine with you?

Perfect! That would be fine with me. 😊

[ElectreAAS]

I really like the new organization! Just a nitpicky question: in "Getting Started/Stanza Reference/dune" (renamed into "Reference Manual/Files/dune"), some items in the list on the left have subsections: executable, install, mdx, & rule. In the latest version we can see which ones have subsections, even when they're not selected: (the little + sign).

In the version from this PR, this little + sign is gone.

Is that intended? Is it important? I personnaly don't think it's important, as it's not really highlighting which components are important, rather those with special rules attached to them. Still wanted to point that out just in case

[emillon]

In the latest version we can see which ones have subsections, even when they're not selected: (the little + sign).

Yes, that's intended (I think). It's because we're reaching the end of the html toc depth. I think that's good because it's unlikely we'll need to click on say "linking modes" from a different stanza.

Thanks!

[nojb]

Sorry I'm coming late to the discussion. The reorganization in terms of files seems file. However, the Dune file stanza reference is now even deeper in the TOC: Reference Manual > Files > dune. Without altering the file layout, would it be possible to have a top-level link to this content somehow? In my experience this is the most consulted part of the manual.