Update quickstart to suggest dune init proj

Signed-off-by: Shon Feder <[email protected]>

doc/dune-files.rst

@@ -2,6 +2,8 @@
 Stanza reference
 ****************
 
+.. _dune-project:
+
 dune-project
 ============
 
@@ -397,6 +399,8 @@ Note that ``dune`` continues to be accepted even after enabling this option, but
 if a file named ``dune-file`` is found in a directory, it will take precedence
 over ``dune``.
 
+.. _dune-files:
+
 dune
 ====
 
@@ -688,6 +692,8 @@ library whose name is not prefixed by the package name. Such a library cannot be
 defined in Dune, but other build systems allow it and this feature is meant to
 help migration from those systems.
 
+.. _executable:
+
 executable
 ----------
 

doc/quick-start.rst

@@ -6,10 +6,148 @@ This document gives simple usage examples of Dune. You can also look at
 `examples <https://github.com/ocaml/dune/tree/master/example>`__ for complete
 examples of projects using Dune.
 
+Initializing projects
+=====================
+
+The following subsections illustrate basic usage of the ``dune init proj``
+subcommand. For more documentation see :ref:`initializing_components` and the
+inline help available from ``dune init --help``.
+
+.. _initializing-an-executable:
+
+Initializing an executable
+--------------------------
+
+To initialize a project to build an executable program, run the following
+(replacing ``project_name`` with the name of your project):
+
+.. code:: shell
+
+    dune init proj project_name
+
+This will create a directory for the project that includes the following contents:
+
+.. code::
+
+    project_name/
+    ├── dune-project
+    ├── test
+    │   ├── dune
+    │   └── project_name.ml
+    ├── lib
+    │   └── dune
+    ├── bin
+    │   ├── dune
+    │   └── main.ml
+    └── project_name.opam
+
+Now, enter your project's directory:
+
+.. code:: shell
+
+   cd project_name
+
+Then, you can build your project with:
+
+.. code:: shell
+
+   dune build
+
+You can run your tests with:
+
+.. code:: shell
+
+   dune test
+
+You can run your program with:
+
+.. code:: shell
+
+   dune exec project_name
+
+The following itemization of the generated content isn't necessary to review at
+this point. But whenever you are ready, it will provide jump-off points from
+which you can dive deeper into Dune's capabilities:
+
+* The ``dune-project`` file specifies metadata about the project, including its
+  name, packaging data (including dependencies), and information about the
+  authors and maintainers.  You should open this in your editor to fill in the
+  placeholder values. See :ref:`dune-project` for details.
+* The ``test`` directory contains a skeleton for your project's tests. Add to
+  the tests by editing ``test/project_name.ml``. See :ref:`writing-tests` for
+  details on testing.
+* The ``lib`` directory will hold the library you write to provide the core
+  functionality of your executable. Add modules to your library by creating new
+  ``.ml`` files in this directory. See :ref:`library` for details on specifying
+  libraries manually.
+* The ``bin`` directory holds a skeleton for the executable program. Within the
+  modules in this directory, you can access the modules in your ``lib`` under
+  the namespace ``Project_name.Mod``, where ``Project_name`` is replaced with
+  the name of your project and ``Mod`` corresponds to the name of the file in
+  the ``lib`` directory. You can run the executable with ``dune exec
+  project_name``.  See :ref:`hello-world-program` for an example of specifying
+  an executable manually and :ref:`executable` for details.
+* The ``project_name.opam`` file will be freshly generated from the
+  ``dune-project`` file whenever you build your project. You shouldn't need to
+  worry about this, but you can see :ref:`opam-generation` for details.
+* The ``dune`` files in each directory specify the component to be built with
+  the files in that directory. For details on dune files, see :ref:`dune-files`.
+
+Initializing a library
+--------------------------
+
+To initialize a project for an ocaml library, run the following (replacing
+``project_name`` with the name of your project):
+
+.. code:: shell
+
+    dune init proj --kind=lib project_name
+
+This will create a directory for the project that includes the following contents:
+
+.. code::
+
+    project_name/
+    ├── dune-project
+    ├── lib
+    │   └── dune
+    ├── test
+    │   ├── dune
+    │   └── project_name.ml
+    └── project_name.opam
+
+Now, enter your project's directory:
+
+.. code:: shell
+
+   cd project_name
+
+Then, you can build your project with:
+
+.. code:: shell
+
+   dune build
+
+You can run your tests with:
+
+.. code:: shell
+
+   dune test
+
+
+All of the sub-components generated are the same as those described in
+:ref:`initializing-an-executable`, with the following exceptions:
+
+* There is no ``bin`` directory generated.
+* The ``dune`` file in the ``lib`` directory specifies that the library should
+  be *public*. See :ref:`library` for details.
+
+.. _hello-world-program:
+
 Building a Hello World Program
 ==============================
 
-Since OCaml is a compiler language, first create a ``dune`` file in Nano, Vim, 
+Since OCaml is a compiled language, first create a ``dune`` file in Nano, Vim,
 or your preferred text editor. Declare the ``hello_world`` executable by including following stanza 
 (shown below). Name this initial file ``dune`` and save it in a directory of your choice. 
 
@@ -113,7 +251,7 @@ And build it with:
 The executable will be built as ``_build/default/hello_world.exe``
 
 Defining a Library Using Lwt and ``ocaml-re``
-=========================================
+=============================================
 
 Write this ``dune`` file:
 
@@ -199,7 +337,7 @@ declare the dependency to this file via:
     (preprocessor_deps config.h)
 
 Using the ``.cppo.ml`` Style Like the ``ocamlbuild`` Plugin
----------------------------------------------------
+-----------------------------------------------------------
 
 Write this in your ``dune`` file:
 
@@ -230,7 +368,7 @@ this ``dune`` file:
      (c_library_flags (-lblah)))
 
 Defining a Library with C Stubs using ``pkg-config``
-================================================
+====================================================
 
 Same context as before, but using ``pkg-config`` to query the
 compilation and link flags. Write this ``dune`` file:

doc/tests.rst

@@ -1,3 +1,5 @@
+.. _writing-tests:
+
 *************************
 Writing and running tests
 *************************

doc/usage.rst

@@ -9,9 +9,6 @@ This section describe usage of dune from the shell.
 Initializing components
 =======================
 
-NOTE: The ``dune init`` command is still under development and subject to
-change.
-
 Dune's ``init`` subcommand provides limited support for generating dune file
 stanzas and folder structures to define components. ``dune init`` can be used to
 quickly add new projects, libraries, tests, or executables without having to