diff --git a/doc/usage.rst b/doc/command-line-interface.rst similarity index 98% rename from doc/usage.rst rename to doc/command-line-interface.rst index e0d21d151d9..ac2194020f4 100644 --- a/doc/usage.rst +++ b/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 ----------------------- diff --git a/doc/conf.py b/doc/conf.py index 2ccdca7ac2d..083e59956a9 100644 --- a/doc/conf.py +++ b/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", +} diff --git a/doc/core-concepts/index.rst b/doc/core-concepts/index.rst new file mode 100644 index 00000000000..7260e57ca7d --- /dev/null +++ b/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 diff --git a/doc/explanation/mental-model.rst b/doc/core-concepts/mental-model.rst similarity index 100% rename from doc/explanation/mental-model.rst rename to doc/core-concepts/mental-model.rst diff --git a/doc/explanation/scopes.rst b/doc/core-concepts/scopes.rst similarity index 100% rename from doc/explanation/scopes.rst rename to doc/core-concepts/scopes.rst diff --git a/doc/core-concepts/terminology.rst b/doc/core-concepts/terminology.rst new file mode 100644 index 00000000000..c135693d3c0 --- /dev/null +++ b/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 + ``/_build`` directory to the :term:`installed world`. + + scope + Defined by any directory that contains at least one `.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 ``/_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 ``/_build/``. + + build target + Specified on the command line, e.g., ``dune build ``. 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 `` 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``"). diff --git a/doc/tutorials/dune-package-management/dependencies.md b/doc/dune-package-management/dependencies.md similarity index 100% rename from doc/tutorials/dune-package-management/dependencies.md rename to doc/dune-package-management/dependencies.md diff --git a/doc/tutorials/dune-package-management/dependencies/constraints b/doc/dune-package-management/dependencies/constraints similarity index 100% rename from doc/tutorials/dune-package-management/dependencies/constraints rename to doc/dune-package-management/dependencies/constraints diff --git a/doc/tutorials/dune-package-management/dependencies/dune b/doc/dune-package-management/dependencies/dune similarity index 100% rename from doc/tutorials/dune-package-management/dependencies/dune rename to doc/dune-package-management/dependencies/dune diff --git a/doc/tutorials/dune-package-management/dependencies/dune-project b/doc/dune-package-management/dependencies/dune-project similarity index 100% rename from doc/tutorials/dune-package-management/dependencies/dune-project rename to doc/dune-package-management/dependencies/dune-project diff --git a/doc/tutorials/dune-package-management/dependencies/test.ml b/doc/dune-package-management/dependencies/test.ml similarity index 100% rename from doc/tutorials/dune-package-management/dependencies/test.ml rename to doc/dune-package-management/dependencies/test.ml diff --git a/doc/tutorials/dune-package-management/index.md b/doc/dune-package-management/index.md similarity index 61% rename from doc/tutorials/dune-package-management/index.md rename to doc/dune-package-management/index.md index 9dc6069ea56..95a57012690 100644 --- a/doc/tutorials/dune-package-management/index.md +++ b/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 diff --git a/doc/tutorials/dune-package-management/pinning.md b/doc/dune-package-management/pinning.md similarity index 100% rename from doc/tutorials/dune-package-management/pinning.md rename to doc/dune-package-management/pinning.md diff --git a/doc/tutorials/dune-package-management/pinning/dune-project b/doc/dune-package-management/pinning/dune-project similarity index 100% rename from doc/tutorials/dune-package-management/pinning/dune-project rename to doc/dune-package-management/pinning/dune-project diff --git a/doc/tutorials/dune-package-management/repos.md b/doc/dune-package-management/repos.md similarity index 100% rename from doc/tutorials/dune-package-management/repos.md rename to doc/dune-package-management/repos.md diff --git a/doc/tutorials/dune-package-management/repos/dune-workspace b/doc/dune-package-management/repos/dune-workspace similarity index 100% rename from doc/tutorials/dune-package-management/repos/dune-workspace rename to doc/dune-package-management/repos/dune-workspace diff --git a/doc/tutorials/dune-package-management/setup.md b/doc/dune-package-management/setup.md similarity index 100% rename from doc/tutorials/dune-package-management/setup.md rename to doc/dune-package-management/setup.md diff --git a/doc/tutorials/dune-package-management/setup/dune b/doc/dune-package-management/setup/dune similarity index 100% rename from doc/tutorials/dune-package-management/setup/dune rename to doc/dune-package-management/setup/dune diff --git a/doc/tutorials/dune-package-management/setup/dune-project b/doc/dune-package-management/setup/dune-project similarity index 100% rename from doc/tutorials/dune-package-management/setup/dune-project rename to doc/dune-package-management/setup/dune-project diff --git a/doc/tutorials/dune-package-management/setup/test.ml b/doc/dune-package-management/setup/test.ml similarity index 100% rename from doc/tutorials/dune-package-management/setup/test.ml rename to doc/dune-package-management/setup/test.ml diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst index 8b8e4e5785e..40d3fdf5da4 100644 --- a/doc/explanation/index.rst +++ b/doc/explanation/index.rst @@ -7,11 +7,9 @@ the rest of the OCaml ecosystem. .. toctree:: :maxdepth: 1 - scopes preprocessing ocaml-ecosystem package-management opam-integration bootstrap - mental-model tour/index diff --git a/doc/explanation/package-management.md b/doc/explanation/package-management.md index c702632fe05..312728b5cea 100644 --- a/doc/explanation/package-management.md +++ b/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: diff --git a/doc/explanation/tour/index.rst b/doc/explanation/tour/index.rst index f751b9afe60..37eb28f35c1 100644 --- a/doc/explanation/tour/index.rst +++ b/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. diff --git a/doc/tutorials/developing-with-dune/conclusion.md b/doc/first-steps-with-dune/conclusion.md similarity index 100% rename from doc/tutorials/developing-with-dune/conclusion.md rename to doc/first-steps-with-dune/conclusion.md diff --git a/doc/tutorials/developing-with-dune/development-cycle.md b/doc/first-steps-with-dune/development-cycle.md similarity index 100% rename from doc/tutorials/developing-with-dune/development-cycle.md rename to doc/first-steps-with-dune/development-cycle.md diff --git a/doc/tutorials/developing-with-dune/development-cycle/lib/ast.ml b/doc/first-steps-with-dune/development-cycle/lib/ast.ml similarity index 100% rename from doc/tutorials/developing-with-dune/development-cycle/lib/ast.ml rename to doc/first-steps-with-dune/development-cycle/lib/ast.ml diff --git a/doc/tutorials/developing-with-dune/development-cycle/lib/cli.ml b/doc/first-steps-with-dune/development-cycle/lib/cli.ml similarity index 100% rename from doc/tutorials/developing-with-dune/development-cycle/lib/cli.ml rename to doc/first-steps-with-dune/development-cycle/lib/cli.ml diff --git a/doc/tutorials/developing-with-dune/development-cycle/lib/lexer.mll b/doc/first-steps-with-dune/development-cycle/lib/lexer.mll similarity index 100% rename from doc/tutorials/developing-with-dune/development-cycle/lib/lexer.mll rename to doc/first-steps-with-dune/development-cycle/lib/lexer.mll diff --git a/doc/tutorials/developing-with-dune/development-cycle/lib/parser.mly b/doc/first-steps-with-dune/development-cycle/lib/parser.mly similarity index 100% rename from doc/tutorials/developing-with-dune/development-cycle/lib/parser.mly rename to doc/first-steps-with-dune/development-cycle/lib/parser.mly diff --git a/doc/tutorials/developing-with-dune/development-cycle/test/calc.t b/doc/first-steps-with-dune/development-cycle/test/calc.t similarity index 100% rename from doc/tutorials/developing-with-dune/development-cycle/test/calc.t rename to doc/first-steps-with-dune/development-cycle/test/calc.t diff --git a/doc/tutorials/developing-with-dune/index.md b/doc/first-steps-with-dune/index.md similarity index 96% rename from doc/tutorials/developing-with-dune/index.md rename to doc/first-steps-with-dune/index.md index e9ab9790a6f..da28caa4e1d 100644 --- a/doc/tutorials/developing-with-dune/index.md +++ b/doc/first-steps-with-dune/index.md @@ -2,7 +2,7 @@ author: Etienne Millon --- -Developing with Dune +Your First Steps with Dune ==================== :::{warning} diff --git a/doc/tutorials/developing-with-dune/interfacing-with-c.md b/doc/first-steps-with-dune/interfacing-with-c.md similarity index 100% rename from doc/tutorials/developing-with-dune/interfacing-with-c.md rename to doc/first-steps-with-dune/interfacing-with-c.md diff --git a/doc/tutorials/developing-with-dune/interfacing-with-c/lib/calc_stubs.c b/doc/first-steps-with-dune/interfacing-with-c/lib/calc_stubs.c similarity index 100% rename from doc/tutorials/developing-with-dune/interfacing-with-c/lib/calc_stubs.c rename to doc/first-steps-with-dune/interfacing-with-c/lib/calc_stubs.c diff --git a/doc/tutorials/developing-with-dune/interfacing-with-c/lib/cli.ml b/doc/first-steps-with-dune/interfacing-with-c/lib/cli.ml similarity index 100% rename from doc/tutorials/developing-with-dune/interfacing-with-c/lib/cli.ml rename to doc/first-steps-with-dune/interfacing-with-c/lib/cli.ml diff --git a/doc/tutorials/developing-with-dune/interfacing-with-c/lib/dune b/doc/first-steps-with-dune/interfacing-with-c/lib/dune similarity index 100% rename from doc/tutorials/developing-with-dune/interfacing-with-c/lib/dune rename to doc/first-steps-with-dune/interfacing-with-c/lib/dune diff --git a/doc/tutorials/developing-with-dune/interfacing-with-c/lib/lexer.mll b/doc/first-steps-with-dune/interfacing-with-c/lib/lexer.mll similarity index 100% rename from doc/tutorials/developing-with-dune/interfacing-with-c/lib/lexer.mll rename to doc/first-steps-with-dune/interfacing-with-c/lib/lexer.mll diff --git a/doc/tutorials/developing-with-dune/interfacing-with-c/test/calc.t b/doc/first-steps-with-dune/interfacing-with-c/test/calc.t similarity index 100% rename from doc/tutorials/developing-with-dune/interfacing-with-c/test/calc.t rename to doc/first-steps-with-dune/interfacing-with-c/test/calc.t diff --git a/doc/tutorials/developing-with-dune/introduction.md b/doc/first-steps-with-dune/introduction.md similarity index 100% rename from doc/tutorials/developing-with-dune/introduction.md rename to doc/first-steps-with-dune/introduction.md diff --git a/doc/tutorials/developing-with-dune/introduction/ast.ml b/doc/first-steps-with-dune/introduction/ast.ml similarity index 100% rename from doc/tutorials/developing-with-dune/introduction/ast.ml rename to doc/first-steps-with-dune/introduction/ast.ml diff --git a/doc/tutorials/developing-with-dune/introduction/calc.ml b/doc/first-steps-with-dune/introduction/calc.ml similarity index 100% rename from doc/tutorials/developing-with-dune/introduction/calc.ml rename to doc/first-steps-with-dune/introduction/calc.ml diff --git a/doc/tutorials/developing-with-dune/introduction/dune b/doc/first-steps-with-dune/introduction/dune similarity index 100% rename from doc/tutorials/developing-with-dune/introduction/dune rename to doc/first-steps-with-dune/introduction/dune diff --git a/doc/tutorials/developing-with-dune/introduction/dune-project b/doc/first-steps-with-dune/introduction/dune-project similarity index 100% rename from doc/tutorials/developing-with-dune/introduction/dune-project rename to doc/first-steps-with-dune/introduction/dune-project diff --git a/doc/tutorials/developing-with-dune/introduction/lexer.mll b/doc/first-steps-with-dune/introduction/lexer.mll similarity index 100% rename from doc/tutorials/developing-with-dune/introduction/lexer.mll rename to doc/first-steps-with-dune/introduction/lexer.mll diff --git a/doc/tutorials/developing-with-dune/introduction/parser.mly b/doc/first-steps-with-dune/introduction/parser.mly similarity index 100% rename from doc/tutorials/developing-with-dune/introduction/parser.mly rename to doc/first-steps-with-dune/introduction/parser.mly diff --git a/doc/tutorials/developing-with-dune/structure.md b/doc/first-steps-with-dune/structure.md similarity index 100% rename from doc/tutorials/developing-with-dune/structure.md rename to doc/first-steps-with-dune/structure.md diff --git a/doc/tutorials/developing-with-dune/structure/bin/calc.ml b/doc/first-steps-with-dune/structure/bin/calc.ml similarity index 100% rename from doc/tutorials/developing-with-dune/structure/bin/calc.ml rename to doc/first-steps-with-dune/structure/bin/calc.ml diff --git a/doc/tutorials/developing-with-dune/structure/bin/dune b/doc/first-steps-with-dune/structure/bin/dune similarity index 100% rename from doc/tutorials/developing-with-dune/structure/bin/dune rename to doc/first-steps-with-dune/structure/bin/dune diff --git a/doc/tutorials/developing-with-dune/structure/lib/cli.ml b/doc/first-steps-with-dune/structure/lib/cli.ml similarity index 100% rename from doc/tutorials/developing-with-dune/structure/lib/cli.ml rename to doc/first-steps-with-dune/structure/lib/cli.ml diff --git a/doc/tutorials/developing-with-dune/structure/lib/dune b/doc/first-steps-with-dune/structure/lib/dune similarity index 100% rename from doc/tutorials/developing-with-dune/structure/lib/dune rename to doc/first-steps-with-dune/structure/lib/dune diff --git a/doc/tutorials/developing-with-dune/structure/test/calc.t b/doc/first-steps-with-dune/structure/test/calc.t similarity index 100% rename from doc/tutorials/developing-with-dune/structure/test/calc.t rename to doc/first-steps-with-dune/structure/test/calc.t diff --git a/doc/tutorials/developing-with-dune/structure/test/dune b/doc/first-steps-with-dune/structure/test/dune similarity index 100% rename from doc/tutorials/developing-with-dune/structure/test/dune rename to doc/first-steps-with-dune/structure/test/dune diff --git a/doc/tutorials/developing-with-dune/unit-tests.md b/doc/first-steps-with-dune/unit-tests.md similarity index 100% rename from doc/tutorials/developing-with-dune/unit-tests.md rename to doc/first-steps-with-dune/unit-tests.md diff --git a/doc/tutorials/developing-with-dune/using-ppx.md b/doc/first-steps-with-dune/using-ppx.md similarity index 100% rename from doc/tutorials/developing-with-dune/using-ppx.md rename to doc/first-steps-with-dune/using-ppx.md diff --git a/doc/tutorials/developing-with-dune/using-ppx/lib/ast.ml b/doc/first-steps-with-dune/using-ppx/lib/ast.ml similarity index 100% rename from doc/tutorials/developing-with-dune/using-ppx/lib/ast.ml rename to doc/first-steps-with-dune/using-ppx/lib/ast.ml diff --git a/doc/tutorials/developing-with-dune/using-ppx/lib/cli.ml b/doc/first-steps-with-dune/using-ppx/lib/cli.ml similarity index 100% rename from doc/tutorials/developing-with-dune/using-ppx/lib/cli.ml rename to doc/first-steps-with-dune/using-ppx/lib/cli.ml diff --git a/doc/tutorials/developing-with-dune/using-ppx/lib/dune b/doc/first-steps-with-dune/using-ppx/lib/dune similarity index 100% rename from doc/tutorials/developing-with-dune/using-ppx/lib/dune rename to doc/first-steps-with-dune/using-ppx/lib/dune diff --git a/doc/tutorials/developing-with-dune/using-ppx/test/calc.t b/doc/first-steps-with-dune/using-ppx/test/calc.t similarity index 100% rename from doc/tutorials/developing-with-dune/using-ppx/test/calc.t rename to doc/first-steps-with-dune/using-ppx/test/calc.t diff --git a/doc/getting-started/index.rst b/doc/getting-started/index.rst deleted file mode 100644 index f3d57c78e06..00000000000 --- a/doc/getting-started/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Getting Started and Core Concepts -================================= - -These documents should be the first ones read by new Dune users. They explain -what Dune is, how it works, and how to use it. - -.. toctree:: - :maxdepth: 2 - - ../overview - ../quick-start - ../usage diff --git a/doc/index.rst b/doc/index.rst index eb4888329c6..d693e3c1bba 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,8 +7,12 @@ 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 diff --git a/doc/overview.rst b/doc/overview.rst index 33321671c11..aa61c122899 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -55,112 +55,10 @@ The first section below defines some terms used in this manual. The second section specifies the Dune metadata format, and the third one describes how to use the ``dune`` command. -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 - ``/_build`` directory to the :term:`installed world`. - - scope - Defined by any directory that contains at least one `.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:`/explanation/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 ``/_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 ``/_build/``. - - build target - Specified on the command line, e.g., ``dune build ``. 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 `` 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``"). - Project Layout ============== -A typical Dune project will have a ``dune-project`` and one or more -``.opam`` files at the root as well as ``dune`` files wherever +A typical Dune project will have a ``dune-project``, as well as ``dune`` files wherever interesting things are: libraries, executables, tests, documents to install, etc. diff --git a/doc/quick-start.rst b/doc/practical-examples.rst similarity index 99% rename from doc/quick-start.rst rename to doc/practical-examples.rst index a2e0a70f116..ca73ca1ddc3 100644 --- a/doc/quick-start.rst +++ b/doc/practical-examples.rst @@ -1,6 +1,6 @@ -********** -Quickstart -********** +****************** +Dune by Example +****************** .. TODO(diataxis) diff --git a/doc/reference/aliases/pkg-install.rst b/doc/reference/aliases/pkg-install.rst index 4c897f274b4..e0fc6e2e5b0 100644 --- a/doc/reference/aliases/pkg-install.rst +++ b/doc/reference/aliases/pkg-install.rst @@ -2,7 +2,7 @@ ============ This alias is only relevant when using Dune with *package management* (see -:doc:`/tutorials/dune-package-management/index`). Running ``dune build +:doc:`/dune-package-management/index`). Running ``dune build @pkg-install`` will fetch the dependencies described in the ``depends`` field of your ``dune-project`` (see :doc:`/reference/dune-project/package`) and build them. It will not build your project. diff --git a/doc/reference/dune-project/index.rst b/doc/reference/dune-project/index.rst index 0df2579adc3..492cbee4367 100644 --- a/doc/reference/dune-project/index.rst +++ b/doc/reference/dune-project/index.rst @@ -2,7 +2,7 @@ dune-project ============ Each ``dune-project`` file marks the root of a Dune projects within the current -Dune workspace (see :doc:`/explanation/scopes`). It can also specify project-wide +Dune workspace (see :doc:`/core-concepts/scopes`). It can also specify project-wide parameters. The first line of ``dune-project`` must be a ``lang`` stanza with no extra diff --git a/doc/reference/dune-workspace/index.rst b/doc/reference/dune-workspace/index.rst index 5b09b965f03..82fdef0042f 100644 --- a/doc/reference/dune-workspace/index.rst +++ b/doc/reference/dune-workspace/index.rst @@ -2,7 +2,7 @@ dune-workspace ============== A ``dune-workspace`` file (if present) marks the root of the current Dune -workspace (see :doc:`/explanation/scopes`). It can be used to define compilation contexts +workspace (see :doc:`/core-concepts/scopes`). It can be used to define compilation contexts (see :doc:`/reference/dune-workspace/context`) and specify settings common to all Dune projects contained within the workspace. diff --git a/doc/reference/dune/index.rst b/doc/reference/dune/index.rst index 71ead589c57..7dfa86e0bbd 100644 --- a/doc/reference/dune/index.rst +++ b/doc/reference/dune/index.rst @@ -2,7 +2,7 @@ dune ==== ``dune`` files are the main part of Dune. Each ``dune`` file belongs to a Dune -project (see :doc:`/explanation/scopes`). They are used to describe libraries, executables, +project (see :doc:`/core-concepts/scopes`). They are used to describe libraries, executables, tests, and everything else Dune needs to know about. The syntax of ``dune`` files is described in diff --git a/doc/requirements.txt b/doc/requirements.txt index 7603f4919b8..4ee02902b42 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,4 +2,5 @@ sphinx >= 6 furo sphinx-copybutton >= 0.5.0 sphinx-design +sphinx-reredirects myst-parser diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md deleted file mode 100644 index 1c6322e96cb..00000000000 --- a/doc/tutorials/index.md +++ /dev/null @@ -1,11 +0,0 @@ -Tutorials -========= - -These tutorials are hands-on lessons to learn about Dune. - -:::{toctree} -:maxdepth: 1 - -developing-with-dune/index -dune-package-management/index -:::