From 46295016286d5448c5eed5941279fbbe29c3a36e Mon Sep 17 00:00:00 2001
From: "Paul R. Tagliamonte" <paultag@debian.org>
Date: Sun, 7 Apr 2013 11:35:10 -0400
Subject: [PATCH] Addining some initial docs.

---
 docs/index.rst                   |  4 +--
 docs/language/api.rst            | 47 ++++++++++++++++++++++++++++++++
 docs/language/index.rst          | 11 ++++++++
 docs/language/internals.rst      | 27 ++++++++++++++++++
 docs/{language => }/tutorial.rst |  0
 5 files changed, 87 insertions(+), 2 deletions(-)
 create mode 100644 docs/language/api.rst
 create mode 100644 docs/language/index.rst
 create mode 100644 docs/language/internals.rst
 rename docs/{language => }/tutorial.rst (100%)

diff --git a/docs/index.rst b/docs/index.rst
index 1618c2f..2e3d41e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -38,5 +38,5 @@ Contents:
 
    quickstart
    hacking
-   language/tutorial
-..   library/index
+   tutorial
+   language/index
diff --git a/docs/language/api.rst b/docs/language/api.rst
new file mode 100644
index 0000000..b29d849
--- /dev/null
+++ b/docs/language/api.rst
@@ -0,0 +1,47 @@
+=================
+Hy (the language)
+=================
+
+
+.. warning::
+    This is incomplete; please consider contributing to the documentation
+    effort.
+
+
+Theory of Hy
+============
+
+Hy maintains, over everything else, 100% compatibility in both directions
+with Python it's self. All Hy code follows a few simple rules. Memorize
+this, it's going to come in handy.
+
+These rules help make sure code is idiomatic and interface-able in both
+languages.
+
+
+  * Symbols in earmufs will be translated to the uppercased version of that
+    string. For example, `*foo*` will become `FOO`.
+
+  * UTF-8 entities will be encoded using
+    `punycode <http://en.wikipedia.org/wiki/Punycode>`_ and prefixed with
+    `__hy_`. For instance, `⚘` will become `__hy_w7h`, and `♥` will become
+    `__hy_g6h`.
+
+  * Symbols that contain dashes will have them replaced with underscores. For
+    example, `render-template` will become `render_template`.
+
+
+Builtins
+========
+
+Hy features a number special forms that are used to help generate
+correct Python AST. The following are "special" forms, which may have
+behavior that's slightly unexpected in some situations.
+
+do / progn
+----------
+
+the `do` or `progn` forms can be used in full code branches. What that means
+is basically `(do)` and `(progn)` can only be used where a Python expression
+can be used. These forms don't actually allow you to break Pythonic internals
+such as `lambda` or `list-comp`, where you can only have one expression.
diff --git a/docs/language/index.rst b/docs/language/index.rst
new file mode 100644
index 0000000..6ca1ffd
--- /dev/null
+++ b/docs/language/index.rst
@@ -0,0 +1,11 @@
+
+Documentation Index
+===================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   api
+   internals
diff --git a/docs/language/internals.rst b/docs/language/internals.rst
new file mode 100644
index 0000000..ccf8263
--- /dev/null
+++ b/docs/language/internals.rst
@@ -0,0 +1,27 @@
+=========================
+Internal Hy Documentation
+=========================
+
+.. info::
+    These bits are for folks who hack on Hy it's self, mostly!
+
+
+Hy Models
+=========
+
+.. TODO::
+    Write this.
+
+
+Hy Macros
+=========
+
+.. TODO::
+    Write this.
+
+
+Hy Compiler Builtins
+====================
+
+.. TODO::
+    Write this.
diff --git a/docs/language/tutorial.rst b/docs/tutorial.rst
similarity index 100%
rename from docs/language/tutorial.rst
rename to docs/tutorial.rst