Finishing up on a baseline docs

docs/guide/design.rst → docs/design.rst

@@ -134,7 +134,7 @@ structure layout with minimal differing options. ``dds`` prescribes the
 
 .. note::
     These prescriptions are not as draconian as they may sound upon first
-    reading. Refer to the :doc:`packages` page for more information.
+    reading. Refer to the :doc:`guide/packages` page for more information.
 
 .. _Pitchfork: https://api.csswg.org/bikeshed/?force=1&url=https://raw.githubusercontent.com/vector-of-bool/pitchfork/develop/data/spec.bs
 
@@ -188,7 +188,7 @@ All Files Compile with the Same Options
 When DDS compiles a library, every source file will be compiled with an
 identical set of options. Additionally, when DDS compiles a dependency tree,
 every library in that dependency tree will be compiled with an identical set of
-options. Refer to the :doc:`toolchains` page for more information.
+options. Refer to the :doc:`guide/toolchains` page for more information.
 
 Currently, the only exception to this rules is for flags that control compiler
 warnings: Dependencies will be compiled without adding any warnings flags,

docs/guide/getting-started.rst

@@ -0,0 +1,26 @@
+Getting Started
+###############
+
+Using ``dds`` is extremely simple:
+
+#. Create a new directory. This will be our *package root*.
+#. Create a subdirectory named ``src/``.
+#. Create a file named ``application.main.cpp``.
+#. Add a ``main()`` function to our new source file.
+#. Depending on your compiler:
+    #. If you are using GCC, run the ``dds build -t :gcc`` command from the
+       package root.
+    #. If you are using Clang, run the ``dds build -t :clang`` command from the
+       package root.
+    #. If you are using Visual C++, run the :code:`dds build -t :msvc` command
+       from the package root from a developer command prompt.
+
+You will now have a ``_build`` directory, and it will contain a newly compiled
+``application``!
+
+Obviously this isn't *all* there is to do with ``dds``. Read on to the next
+pages to learn more.
+
+.. note::
+    You're reading a very early version of these docs. There will be a lot more
+    here in the future. Watch this space for changes!

docs/guide/index.rst

@@ -6,7 +6,7 @@ User Guide
 .. toctree::
     :maxdepth: 2
 
-    design
+    getting-started
     packages
     toolchains
     source-dists

docs/guide/interdeps.rst

@@ -9,6 +9,8 @@ interoperate with other build and packaging tools, we consider the issues of
 package dependencies and library dependencies separately.
 
 
+.. _deps.pkg-deps:
+
 Package Dependencies
 ********************
 

docs/guide/packages.rst

@@ -236,7 +236,15 @@ included in downstream binaries, but it will still generate link rules for the
 dependencies of a header-only library.
 
 In order for ``dds`` to be able to distribute and interlink libraries, a
-``library.dds`` file must be present at the corresponding library root.
+``library.dds`` file must be present at the corresponding library root. The
+only required key in a ``library.dds`` file is ``Name``:
+
+.. code-block:: yaml
+
+    Name: my-library
+
+
+.. seealso:: More information is discussed on the :ref:`deps.lib-deps` page
 
 
 .. _pkgs.pkg-root:
@@ -260,8 +268,7 @@ Packages
 ********
 
 A package is defined by some *package root*, and contains some number of
-*libraries*. In order for a package to be exported by ``dds`` it must have a
-``package.dds`` file at its package root.
+*libraries*.
 
 The primary distribution format of packages that is used by ``dds`` is the
 *source distribution*. Refer to the page :doc:`source-dists`.
@@ -270,3 +277,23 @@ Packages are identified by a name/version pair, joined together by an ``@``
 symbol. The version of a package must be a semantic version string. Together,
 the ``name@version`` string forms the *package ID*, and it must be unique
 within a repository or package catalog.
+
+In order for a package to be exported by ``dds`` it must have a
+``package.dds`` file at its package root. Three keys are required to be
+present in the ``package.dds`` file: ``Name``, ``Version``, and ``Namespace``:
+
+.. code-block:: yaml
+
+    Name: acme-widgets
+    Version: 6.7.3
+    Namespace: acme
+
+``Version`` must be a valid semantic version string.
+
+.. note::
+    The ``Namespace`` key is arbitrary, and not necessarily associated with
+    and C++ ``namespace``.
+
+.. seealso::
+  The purpose of ``Namespace``, as well as additional options in this file,
+  are described in the :ref:`deps.pkg-deps` page

docs/index.rst

@@ -9,12 +9,13 @@ learn, but I'm glad you're here! I hope you find ``dds`` useful to you and your
 projects.
 
 If you're completely new and have no idea what the project is about, check out
-the :doc:`guide/design` page to get started.
+the :doc:`guide/getting-started` page.
 
 .. toctree::
     :maxdepth: 2
 
     guide/index
+    design
 
 
 Indices and tables