add md support, first quickstart structure

README.md

@@ -6,7 +6,7 @@ Written in [reStructuredText](http://sphinx-doc.org/rest.html) and built using
 
 Setup
 
-    pip install sphinx sphinx-autobuild
+    pip install -r requirements.txt
 
 Build locally
 

conf.py

@@ -16,6 +16,8 @@
 import os
 import shlex
 
+from recommonmark.parser import CommonMarkParser
+
 # 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.
@@ -36,10 +38,14 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

doc/quickstart/quickstart-hackers.md

@@ -0,0 +1,8 @@
+# Getting Started for Hackers
+
+You want to use your own hardware or a virtual machine?
+You're at the right place! If you just want to use the CloudFleet Blimp,
+better go [here](quickstart.html) instead.
+
+TODO: quickest possible way to get started for hackers, with any potential
+side-stories being linked to elsewhere in the docs.

doc/quickstart/quickstart.md

@@ -0,0 +1,8 @@
+# Getting Started
+
+This document describes how to set up your new CloudFleet Blimp.
+If you feel more adventurous and would like to use your own device,
+like a Raspberry Pi, jump right [here](quickstart-hackers.html).
+
+TODO: quickest possible way to get started for new customers, with any potential
+side-stories being linked to elsewhere in the docs.

doc/security/security.md

@@ -0,0 +1,6 @@
+# Security
+
+*In this document we give a technical overview of CloudFleet security*
+
+TODO: detailed list of used methods, protocols, diagrams with links that
+branch off into different documents if necessary...

index.rst

@@ -7,22 +7,32 @@ CloudFleet Documentation
 ========================
 
 Welcome to the CloudFleet Documentation! Let's try to help you get started as
-soon as possible. Do you have your CloudFleet Blimp? If not, then you should
-`order`_ it now.
+soon as possible. Do you have your CloudFleet Blimp? If not, then you can
+`order`_ it now. You can also use your existing device, such as a Raspberry Pi.
 
 .. _order: https://cloudfleet.io/
 
+If you're new here, we recommend that you start by reading
+the `Getting Started guide <doc/quickstart/quickstart.html>`_.
+
 Table of Contents
 -----------------
 
+Quick Start:
+
 .. toctree::
    :maxdepth: 2
 
+   doc/quickstart/quickstart
+   doc/quickstart/quickstart-hackers
+
+Documentation:
 
+.. Add other more detailed topics here like:
+   software usage instructions, support instructions, contributing manual for
+   hackers and high-level code organisation, security aspects
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   doc/security/security

requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx-autobuild
+recommonmark