From 33b0246f1d13d2bbc973ebffb946ea5f90ecf419 Mon Sep 17 00:00:00 2001
From: Radomir Dopieralski <openstack@sheep.art.pl>
Date: Mon, 25 Jul 2016 19:28:53 +0200
Subject: [PATCH] Add intro and directory structure description

---
 .gitignore      |  1 +
 directories.rst | 61 +++++++++++++++++++++++++++++++++++++++++++++++++
 index.rst       |  4 +++-
 intro.rst       |  7 ++++++
 4 files changed, 72 insertions(+), 1 deletion(-)
 create mode 100644 directories.rst
 create mode 100644 intro.rst

diff --git a/.gitignore b/.gitignore
index 72364f9..b8d1a98 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ __pycache__/
 .Python
 env/
 build/
+_build/
 develop-eggs/
 dist/
 downloads/
diff --git a/directories.rst b/directories.rst
new file mode 100644
index 0000000..d48c8a4
--- /dev/null
+++ b/directories.rst
@@ -0,0 +1,61 @@
+Directory Structure
+*******************
+
+The MicroPython repository is divided into a number of directories, each with
+its own function. Some of them include:
+
+
+Docs, Logo and Examples
+=======================
+
+The user documentation for all ports lives in the ``docs`` directory, with some
+example code in the ``examples`` directory. The ``logo`` directory contains the
+MicroPython logo in various formats.
+
+
+Tests
+=====
+
+All tests live in the ``tests`` directory.
+
+
+Python Code
+===========
+
+The ``py`` directory contains the bulk of code for the compiler, runtime
+environment and core library of MicroPython. This is where we will be looking
+for API functions and macros.
+
+
+Port-specific Code
+==================
+
+The directories such as ``esp8266``, ``cc3200``, ``pic16bit``, ``teensy``,
+``stmhal``, ``bare-arm``, ``qemu-arm``, ``unix`` and ``windows`` contain code
+and tools specific to particular ports of MicroPython. If you are working on a
+feature to be added for a specific hardware, this is probably the best place to
+put your files.
+
+
+Minimal Port
+============
+
+The ``minimal`` directory contains the minimum of files that a new port needs.
+You can use this as a template for starting new ports of MicroPython.
+
+
+Common Parts
+============
+
+The ``extmod`` directory contains source of MicroPython modules that may are
+not part of the core library, but are useful for multiple ports. The
+``drivers`` directory has code for libraries that communicate with various
+additional hardware, such as displays or sensors.
+
+
+Tools and Utilities
+===================
+
+The ``tools`` directory contains various tools useful for working with
+MicroPython. The ``mpy-cross`` directory has code for the MicroPython
+cross-compiler, which can be used to generate frozen bytecode modules.
diff --git a/index.rst b/index.rst
index 950a7f4..133d200 100644
--- a/index.rst
+++ b/index.rst
@@ -9,8 +9,10 @@ Welcome to MicroPython Development Documentation's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
+    intro.rst
+    directories.rst
 
 
 Indices and tables
diff --git a/intro.rst b/intro.rst
new file mode 100644
index 0000000..ee470ff
--- /dev/null
+++ b/intro.rst
@@ -0,0 +1,7 @@
+Introduction
+************
+
+This is an unofficial MicroPython development guide. It was written to make it
+easier for new developers to start contributing code to the MicroPython
+project. It's not comprehensive, and at times might even be wrong, but it is
+some starting point.