doc: mention opam file templates (#12710)

Fixes #11177

Signed-off-by: Ali Caglayan <[email protected]>

Author: Alizter

doc/reference/dune-project/generate_opam_files.rst

@@ -20,3 +20,13 @@ generate_opam_files
 With this field, every time one calls Dune to execute some rules (either via
 ``dune build``, ``dune runtest``, or something else), the opam files get
 generated.
+
+To add opam fields not directly supported by ``dune-project``, you can use
+``<package-name>.opam.template`` files (see :doc:`/reference/packages`).
+
+.. seealso::
+
+   :doc:`/reference/dune-project/package` for fields supported by
+   ``dune-project``
+
+   :doc:`/reference/packages` for more information on ``opam.template`` files

doc/reference/packages.rst

@@ -10,39 +10,47 @@ How Dune Knows About Packages
 
 Packages can be defined in two ways:
 
-- If a ``pkg.opam`` file is found, it signals the existence of the ``pkg``
-  package to Dune. The contents of the opam file are not interpreted by Dune.
-- In ``dune-project``, a ``(package)`` stanza with ``(name pkg)`` defines the
-  ``pkg`` package.
+- If a ``<package-name>.opam`` file is found, it signals the existence of the
+  ``<package-name>`` package to Dune. The contents of the opam file are not
+  interpreted by Dune, unless :doc:`package management
+  <../explanation/package-management>` is :doc:`enabled <config/pkg>`.
+
+- In ``dune-project``, a :doc:`(package) <dune-project/package>` stanza with
+  ``(name <package-name>)`` defines the ``<package-name>`` package.
 
 .. note::
 
    If you want to define public elements but are not interested in publishing
    to opam, it is not necessary to write empty ``*.opam`` files. Instead,
-   prefer declaring it in ``dune-project`` as a ``(package)`` with just a
-   ``(name)``.
+   prefer declaring it in ``dune-project`` as a :doc:`(package)
+   <dune-project/package>` with just a ``(name)``.
 
 Generating Opam Files
 ---------------------
 
-In the latter case, if ``(generate_opam_files)`` is present in
-``(dune-project)``, Dune will generate ``pkg.opam`` using the metadata in found in ``(package)`` stanzas and global fields such as ``(source)``.
+In the latter case, if :doc:`(generate_opam_files)
+<dune-project/generate_opam_files>` is present in ``(dune-project)``, Dune will
+generate ``<package-name>.opam`` using the metadata in found in :doc:`(package)
+<dune-project/package>` stanzas and global fields such as ``(source)``.
 
 .. seealso:: :doc:`../howto/opam-file-generation`
 
-If a ``pkg.opam.template`` file is found, the fields found in this opam file
-are added to the generated file, overriding the generated ones in case of
-collision. This can be used as an escape hatch to add arbitrary opam fields.
+If a ``<package-name>.opam.template`` file is found, the fields found in this
+opam file are added to the generated file, overriding the generated ones in
+case of collision. This can be used as an escape hatch to add arbitrary opam
+fields.
+
+.. seealso:: :doc:`dune-project/package` for fields supported by ``dune-project``
 
 What Dune Installs
 ------------------
 
 Dune will install the following files:
 
 - ``(library)`` stanzas which have a ``(public_name)``. The package name is the
-  first component of the dot-separated public name: ``(public_name pkg)`` and
-  ``(public_name pkg.sub)`` will look for a package named ``pkg`` to install
-  their contents.
+  first component of the dot-separated public name: ``(public_name
+  <package-name>)`` and ``(public_name <package-name>.sub)`` will look for a
+  package named ``<package-name>`` to install their contents.
 - ``(executable)`` and ``(test)`` stanzas with a ``(public_name)``. The package
   to install the files in is determined by the ``(package)`` field, which can
   be omitted if there is only one package.