Improved documentation and added a new version of the 'Getting starte…

…d' page

Makefile

@@ -21,3 +21,6 @@ spec:
 	py.test --spec -p no:sugar
 
 travis: install lint isort coverage
+
+docs:
+	cd docs && rm -rf _build && make html

docs/_static/custom_theme.css

@@ -0,0 +1,14 @@
+#features_wrapper{
+  display: flex;
+  flex-wrap: wrap;
+}
+#features_wrapper .feature {
+  margin: 0.5em;
+  padding: 0.5em;
+  flex: 1 1 auto;
+  width: 200px;
+  background: #eee;
+  border-radius: 2px;
+  border: 1px solid #dedede;
+  text-align: center;
+}

docs/_templates/indexcontent.html

@@ -0,0 +1,33 @@
+{%- extends "layout.html" %}
+
+{% set title = _("Welcome to LXD-Nomad's documentation!") %}
+
+{% block body %}
+<div class="figure align-center" id="id1">
+  <h1>LXD-Nomad</h1>
+  <p>Build and orchestrate your development environments with <a href="https://www.ubuntu.com/cloud/lxd" target="_blank">LXD</a> - a.k.a. Vagrant is Too Heavy&trade;</p>
+  <a href="{{ pathto("getting_started") }}" class="btn btn-primary" title="Getting started"><span class="fa fa-bolt">&nbsp;Getting started</span></a>
+</div>
+<div class="figure align-center" id="id2">
+  <p>LXD-Nomad is a wrapper around <a href="https://www.ubuntu.com/cloud/lxd" target="_blank">LXD</a> that allows developers to orchestrate their development environment using a worklow similar to Vagrant.</p>
+</div>
+<div class="figure align-center" id="id3">
+  <h2>Why use LXD-Nomad?</h2>
+</div>
+<div class="figure align-center" id="id4">
+  <p><strong>It's fast.</strong> LXD-Nomad is much <em>much</em> faster than a typical Vagrant + Virtualbox setup.</p>
+  <p><strong>Multi-arch.</strong> Vagrant has been designed with Virtualbox and x86 in mind. Even if you use alternative providers, you’re going to have to jump through inelegant hoops to have your Vagrantfile work on x86 and arm (for example) at the same time because the very concept of a Vagrant box is arch-specific.</p>
+  <p><strong>Simpler.</strong> When working with containers, much of the complexity of Vagrant becomes useless. Why the need for special "vagrant-prepared" boxes when <code class="docutils literal"><span class="pre">lxc exec</span></code> is available? It's much simpler to use whatever images are provided directly by LXD. By removing the need to manage boxes, nomad suddenly becomes much simpler (a simple wrapper around lxd, really).</p>
+</div>
+<div class="figure align-center" id="id5">
+  <h2>Features</h2>
+</div>
+<div id="features_wrapper">
+  <div class="feature"><span class="fa fa-cubes">&nbsp;Multi-container</span></div>
+  <div class="feature"><span class="fa fa-gears">&nbsp;Multi-arch</span></div>
+  <div class="feature"><span class="fa fa-bolt">&nbsp;Fast &amp; Intuitive</span></div>
+  <div class="feature"><span class="fa fa-folder">&nbsp;Shared folders</span></div>
+  <div class="feature"><span class="fa fa-linux">&nbsp;Various distributions</span></div>
+  <div class="feature"><span class="fa fa-rocket">&nbsp;Automated provisioning</span></div>
+</div>
+{% endblock body %}

docs/conf.py

@@ -16,10 +16,15 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('..'))
+
+nomad = __import__('nomad')
+
+ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'  # Are we on ReadTheDocs???
 
 
 # -- General configuration ------------------------------------------------
@@ -35,6 +40,9 @@
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
+html_additional_pages = {
+    'index': 'indexcontent.html',
+}
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -55,9 +63,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2.0'
+version = nomad.__version__
 # The full version, including alpha/beta/rc tags.
-release = '0.2.0'
+release = nomad.__version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -83,7 +91,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'default'
+
+if not ON_RTD:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -103,6 +116,10 @@
 htmlhelp_basename = 'LXD-Nomaddoc'
 
 
+def setup(app):
+    app.add_stylesheet('custom_theme.css')
+
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
@@ -152,6 +169,3 @@
      author, 'LXD-Nomad', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-

docs/getting_started.rst

@@ -0,0 +1,79 @@
+Getting started
+===============
+
+Requirements
+------------
+
+* `Python`_ 3.4+
+* `LXD`_ 2.0+
+* ``getfacl/setfacl`` if you plan to use shared folders
+* any provisioning tool you wish to use with LXD-Nomad
+
+.. _Python: https://www.python.org
+.. _LXD: https://www.ubuntu.com/cloud/lxd
+
+Building nomad on Linux
+-----------------------
+
+LXD-Nomad should build very easily on Linux provided you have LXD available on your system.
+
+Prerequisite: install LXD
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may want to skip this section if you already have a working installation of LXD on your system.
+
+For Debian and Ubuntu, the following command will ensure that LXD is installed:
+
+.. code-block:: console
+
+  $ sudo apt-get install lxd
+
+.. note::
+
+  If you're using an old version of Ubuntu you should first add the LXD's apt repository and install
+  the ``lxd`` package as follows:
+
+  .. code-block:: console
+
+    $ sudo add-apt-repository -y ppa:ubuntu-lxc/lxd-stable
+    $ sudo apt-get update
+    $ sudo apt-get install lxd
+
+You should now be able to configure your LXD installation using:
+
+.. code-block:: console
+
+  $ newgrp lxd  # ensure your current user can use LXD
+  $ sudo lxd init
+
+.. note::
+
+  The ``lxd init`` command will ask you to choose the settings to apply to your LXD installation in
+  an interactive way (storage backend, network configuration, etc). But if you just want to go fast
+  you can try the following commands:
+
+  .. code-block:: console
+
+    $ newgrp lxd
+    $ sudo lxd init --auto
+    $ sudo lxc network create lxdbr0 ipv6.address=none ipv4.address=10.0.3.1/24 ipv4.nat=true
+    $ sudo lxc network attach-profile lxdbr0 default eth0
+
+You can now check if your LXD installation is working using:
+
+  .. code-block:: console
+
+    $ lxc launch ubuntu: first-machine && lxc exec first-machine bash
+
+.. note::
+
+  You can use ``lxd stop first-machine`` to stop the previously created container.
+
+Install LXD-Nomad
+~~~~~~~~~~~~~~~~~
+
+Yoi should now be able to install LXD-Nomad using:
+
+.. code-block:: console
+
+  $ pip3 install git+git://github.com/lxd-nomad/lxd-nomad.git

docs/index.rst

@@ -1,54 +1,18 @@
-LXD-Nomad: because Vagrant is too heavy
-=======================================
+#####################################
+Welcome to LXD-Nomad's documentation!
+#####################################
 
-.. This is a verbatim copy of the README. Sure, it's annoying to have to keep them in sync, but
-   the content should stabilize at some point and we won't have to sync it very often anymore.
-
-*LXD-Nomad* is a wrapper around LXD_ that allows a workflow similar to Vagrant_.
-
-Why LXD-Nomad?
---------------
-
-**It's fast.** LXD-Nomad is much *much* faster than a typical Vagrant + Virtualbox setup.
-
-**Multi-arch.** Vagrant has been designed with Virtualbox and x86 in mind. Even if you use
-alternative providers, you're going to have to jump through inelegant hoops to have your
-``Vagrantfile`` work on x86 and arm (for example) at the same time because the very concept of a
-Vagrant box is arch-specific.
-
-LXD transparently refers to containers of your native arch in the same namespace. Pulling
-``debian/jessie`` gets you an image of the proper arch whether you're on ``x86_64`` or ``arm``.
-
-**Simpler.** When working with containers, much of the complexity of Vagrant becomes useless. Why
-the need for special "vagrant-prepared" boxes when ``lxc exec`` is available? It's much simpler to
-use whatever images are provided directly by lxd. By removing the need to manage boxes, ``nomad``
-suddenly becomes much simpler (a simple wrapper around lxd, really).
-
-Status
-------
-
-Pretty usable, work in progress.
-
-Limitations
------------
-
-Except for the first one, all these limitations are temporary.
-
-**Linux only.** LXD is a manager for Linux containers it only runs on Linux. It doesn't have a thin
-VM layer like Docker has (yet?).
-
-**Debian family guests.** So far, basic guest provisioning has been debian-centric.
-
-**Ansible provisioning.** There isn't support for other provisioning tools yet.
-
-Contents
---------
 
 .. toctree::
    :maxdepth: 2
 
-   user/install
+   getting_started
    user/usage
 
-.. _LXD: https://linuxcontainers.org/lxd/
-.. _Vagrant: https://www.vagrantup.com/
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

requirements-dev.txt

@@ -14,3 +14,7 @@ tox>=1.7
 # Lint / isort
 isort>=4.2
 flake8>=2.2.5
+
+# Docs
+Sphinx>=1.3
+sphinx-rtd-theme>=0.1