Rearrange docs to make the content more discoverable for newcomers

doc/usage.rst → doc/command-line-interface.rst

@@ -1,6 +1,6 @@
-**********************
-Command-Line Interface
-**********************
+********************************************
+How to Use Dune's Command-Line Interface
+********************************************
 
 .. TODO(diataxis)
 
@@ -11,7 +11,7 @@ Command-Line Interface
    - reference info about the CLI
    - how-to info about overriding what ``dune build`` does
 
-This section describes using ``dune`` from the shell.
+This guide describes using ``dune`` from the shell.
 
 .. _initializing_components:
 
@@ -216,7 +216,7 @@ targets upon starting:
     - _build/4.04.0/bin/prog.exe
 
 If a target starts with the ``@`` sign, it is interpreted as an :term:`alias`.
-See :doc:`reference/aliases`.
+See :doc:`/reference/aliases`.
 
 Variables for Artifacts
 -----------------------

doc/conf.py

@@ -66,6 +66,7 @@ def setup(app: Sphinx):
 extensions = [
     'sphinx_copybutton',
     'sphinx_design',
+    'sphinx_reredirects',
     'myst_parser',
 ]
 
@@ -197,3 +198,42 @@ def setup(app: Sphinx):
      author, 'dune', 'One line description of project.',
      'Miscellaneous'),
 ]
+
+redirects = {
+#  rename doc/{usage.rst => command-line-interface.rst} (98%)
+#  rename doc/{explanation => core-concepts}/mental-model.rst (100%)
+#  rename doc/{explanation => core-concepts}/scopes.rst (100%)
+    "usage": "command-line-interface.html",
+    "explanation/mental-model": "../core-concepts/mental-model.html",
+    "explanation/scopes": "../core-concepts/scopes.html",
+
+#  rename doc/{tutorials => }/dune-package-management/dependencies.md (100%)
+#  rename doc/{tutorials => }/dune-package-management/index.md (78%)
+#  rename doc/{tutorials => }/dune-package-management/pinning.md (100%)
+#  rename doc/{tutorials => }/dune-package-management/repos.md (100%)
+#  rename doc/{tutorials => }/dune-package-management/setup.md (100%)
+    "tutorials/dune-package-management": "../../dune-package-management.html",
+    "tutorials/dune-package-management/dependencies/constraints": "../../dune-package-management/dependencies/constraints.html",
+    "tutorials/dune-package-management/dependencies": "../../dune-package-management/dependencies.html",
+    "tutorials/dune-package-management/index": "../../dune-package-management/index.html",
+    "tutorials/dune-package-management/pinning": "../../dune-package-management/pinning.html",
+    "tutorials/dune-package-management/repos": "../../dune-package-management/repos.html",
+    "tutorials/dune-package-management/setup": "../../dune-package-management/setup.html",
+
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/conclusion.md (100%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/development-cycle.md (100%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/index.md (96%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/interfacing-with-c.md (100%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/introduction.md (100%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/structure.md (100%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/unit-tests.md (100%)
+#  rename doc/{tutorials/developing-with-dune => first-steps-with-dune}/using-ppx.md (100%)
+    "tutorials/developing-with-dune/conclusion": "../../first-steps-with-dune/conclusion.html",
+    "tutorials/developing-with-dune/development-cycle": "../../first-steps-with-dune/development-cycle.html",
+    "tutorials/developing-with-dune/index": "../../first-steps-with-dune/index.html",
+    "tutorials/developing-with-dune/interfacing-with-c": "../../first-steps-with-dune/interfacing-with-c.html",
+    "tutorials/developing-with-dune/introduction": "../../first-steps-with-dune/introduction.html",
+    "tutorials/developing-with-dune/structure": "../../first-steps-with-dune/structure.html",
+    "tutorials/developing-with-dune/unit-tests": "../../first-steps-with-dune/unit-tests.html",
+    "tutorials/developing-with-dune/using-ppx": "../../first-steps-with-dune/using-ppx.html",
+}

doc/core-concepts/index.rst

@@ -0,0 +1,11 @@
+Core Concepts
+=================================
+
+These documents explain what Dune is, how it works, and how to use it.
+
+.. toctree::
+   :maxdepth: 2
+
+   mental-model
+   scopes
+   terminology

doc/core-concepts/terminology.rst

@@ -0,0 +1,101 @@
+
+Terminology
+===========
+
+.. glossary::
+   root
+     The top-most directory in a GitHub repo, workspace, and project,
+     differentiated by variables such as ``%{workspace_root}`` and
+     ``%{project_root}``. Dune builds things from this directory. It knows how to
+     build targets that are descendants of the root. Anything outside of the tree
+     starting from the root is considered part of the :term:`installed world`.
+     Refer to :ref:`finding-root` to learn how the workspace root is determined.
+
+   workspace
+     The subtree starting from each root. It can contain any number of projects
+     that will be built simultaneously by Dune, and it must contain a
+     ``dune-workspace`` file.
+
+   project
+     A collection of source files that must include a ``dune-project`` file. It
+     may also contain one or more packages. A project consists in a hierarchy
+     of directories. Every directory (at the root, or a subdirectory) can
+     contain a ``dune`` file that contains instructions to build files in that
+     directory. Projects can be shared between different applications.
+
+   package
+     A set of libraries and executables that opam builds and installs as one.
+
+   installed world
+     Anything outside of the workspace. Dune doesn't know how to build things
+     in the installed world.
+
+   installation
+     The action of copying build artifacts or other files from the
+     ``<root>/_build`` directory to the :term:`installed world`.
+
+   scope
+     Defined by any directory that contains at least one `<package>.opam` file.
+     Typically, every project defines a single scope that is a subtree starting
+     from this directory. Moreover, scopes are separate from your project's
+     dependencies. The scope also determines where private items are visible.
+     Private items include libraries or binaries that will not be installed.
+     See :doc:`/core-concepts/scopes` for more details.
+
+   build context
+     A specific configuration written in a
+     :doc:`/reference/dune-workspace/index` file, which has a
+     corresponding subdirectory in the ``<root>/_build`` directory. It contains
+     all the workspace's build artifacts. Without this specific configuration
+     from the user, there is always a ``default`` build context that
+     corresponds to the executed Dune environment.
+
+   build context root
+     The root of a build context named ``foo`` is ``<root>/_build/<foo>``.
+
+   build target
+     Specified on the command line, e.g., ``dune build <target_path.exe>``. All
+     targets that Dune knows how to build live in the ``_build`` directory.
+
+   alias
+     A build target that doesn't produce any file and has configurable
+     dependencies. Targets starting with ``@`` on the command line are
+     interpreted as aliases (e.g., ``dune build @src/runtest``). Aliases are
+     per-directory. See :doc:`/reference/aliases`.
+
+   environment
+     Determines the default values of various parameters, such as the
+     compilation flags. In Dune, each directory has an environment attached to
+     it. Inside a scope, each directory inherits the environment from its
+     parent. At the root of every scope, a default environment is used. At any
+     point, the environment can be altered using an
+     :doc:`/reference/dune/env` stanza.
+
+   build profile
+     A global setting that influences various defaults. It can be set from the
+     command line using ``--profile <profile>`` or from ``dune-workspace``
+     files. The following profiles are standard:
+
+     -  ``release`` which is the profile used for opam releases
+     -  ``dev`` which is the default profile when none is set explicitly, it has
+        stricter warnings than the ``release`` one
+
+   dialect
+     An alternative frontend to OCaml (such as ReasonML). It is described
+     by a pair of file extensions, one corresponding to interfaces and one to
+     implementations. It can use the standard OCaml syntax, or it can specify an
+     action to convert from a custom syntax to a binary OCaml abstract syntax
+     tree. It can also specify a custom formatter.
+
+   placeholder substitution
+     A build step in which placeholders such as ``%%VERSION%%`` in source files
+     are replaced by concrete values such as ``1.2.3``. It is performed by
+     :ref:`dune-subst` for development versions and dune-release_ for
+     releases.
+
+   stanza
+     A fragment of a file interpreted by Dune, that will appear as a
+     s-expression at the top-level of a file. For example, the
+     :doc:`/reference/dune/library` stanza describes a library. This can be
+     either a generic term ("the library stanza") or it can refer to a
+     particular instance in a file ("the executable stanza in ``bin/dune``").

doc/tutorials/dune-package-management/index.md → doc/dune-package-management/index.md

@@ -2,7 +2,7 @@
 author: Marek Kubica
 ---
 
-OCaml Package Management With Dune
+Package Management With Dune
 ==================================
 
 :::{warning}
@@ -11,12 +11,14 @@ change.
 :::
 
 In this tutorial we will be looking at how to use Dune for managing project
-dependencies. This enables users to install the compiler as well as third-party
+dependencies for OCaml projects. This enables users to install the compiler as well as third-party
 dependencies using a single tool which takes care of building code and
 dependencies.
 
 To get started you only need Dune. Head to {doc}`setup` to begin the setup.
 
+In case you are dealing with an existing OCaml project using `opam`, or you want to use `opam` to manage your project's dependencies, see {doc}`/howto/opam-file-generation`.
+
 :::{toctree}
 :hidden:
 :maxdepth: 1

doc/explanation/index.rst

@@ -7,8 +7,6 @@ the rest of the OCaml ecosystem.
 .. toctree::
    :maxdepth: 1
 
-   mental-model
-   scopes
    preprocessing
    ocaml-ecosystem
    package-management

doc/explanation/package-management.md

@@ -6,7 +6,7 @@ builds packages. Thus it is aimed at people who want to understand how the
 feature works, not how it is used.
 
 For a tour on how to apply package management to a project, refer to the
-{doc}`/tutorials/dune-package-management/index` tutorial.
+{doc}`/dune-package-management/index` tutorial.
 
 ## Motivation
 
@@ -183,7 +183,7 @@ in the build step.
 ### Building
 
 When building, Dune will read the information from the lock directory and set
-up rules for the packages. Check {doc}`/explanation/mental-model` for details
+up rules for the packages. Check {doc}`/core-concepts/mental-model` for details
 about rules.
 
 The rules that the package management sets up include:

doc/explanation/tour/index.rst

@@ -10,7 +10,7 @@ A Tour of the Dune Codebase
 
 Let's start with a very high level tour of how ``dune build`` operates.
 
-As explained in :doc:`/explanation/mental-model`, ``dune build`` will interpret
+As explained in :doc:`/core-concepts/mental-model`, ``dune build`` will interpret
 the targets listed on the command line, interpret the ``dune`` files in the
 workspace as rules, and execute the rules relevant to the requested targets.
 

doc/tutorials/developing-with-dune/index.md → doc/first-steps-with-dune/index.md

@@ -2,7 +2,7 @@
 author: Etienne Millon
 ---
 
-Developing with Dune
+Your First Steps with Dune
 ====================
 
 :::{warning}

doc/index.rst

@@ -7,10 +7,15 @@ libraries, run tests, and much more.
 .. toctree::
    :maxdepth: 2
 
-   getting-started/index
-   tutorials/index
+   overview
+   core-concepts/index
+   first-steps-with-dune/index
+   practical-examples
+   command-line-interface
+   dune-package-management/index
    howto/index
    reference/index
    explanation/index
    advanced/index
    misc/index
+   faq

doc/misc/index.rst

@@ -7,6 +7,5 @@ information about the project itself.
 .. toctree::
    :maxdepth: 2
 
-   ../faq
    ../goals
    ../hacking