Add initial documentation.

README.rst

@@ -3,8 +3,13 @@ astor -- AST observe/rewrite
 =============================
 
 :PyPI: https://pypi.python.org/pypi/astor
+:Documentation: http://astor.rtfd.org/
 :Source: https://github.com/berkerpeksag/astor
 :License: 3-clause BSD
+:Build status:
+    .. image:: https://secure.travis-ci.org/berkerpeksag/astor.png
+        :alt: Travis CI
+        :target: http://travis-ci.org/berkerpeksag/astor/
 
 astor is designed to allow easy manipulation of Python source via the AST.
 

docs/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."

docs/conf.py

+# coding: utf-8
+
+import os.path
+import sys
+import time
+
+sys.path.append(os.path.pardir)
+
+import setuputils
+
+extensions = []
+
+templates_path = ['_templates']
+
+source_suffix = '.rst'
+
+master_doc = 'index'
+
+project = u'astor'
+copyright = u'2013-%s, Berker Peksag' % time.strftime('%Y')
+
+version = release = setuputils.find_version('astor/__init__.py')
+
+exclude_patterns = ['_build']
+
+pygments_style = 'sphinx'
+
+try:
+    import sphinx_rtd_theme
+except ImportError:
+    html_theme = 'default'
+else:
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+htmlhelp_basename = 'astordoc'

docs/index.rst

+.. currentmodule:: astor
+
+============================
+astor -- AST observe/rewrite
+============================
+
+:PyPI: https://pypi.python.org/pypi/astor
+:Source: https://github.com/berkerpeksag/astor
+:Issues: https://github.com/berkerpeksag/astor/issues/
+:License: 3-clause BSD
+:Build status:
+    .. image:: https://secure.travis-ci.org/berkerpeksag/astor.png
+        :alt: Travis CI
+        :target: http://travis-ci.org/berkerpeksag/astor/
+
+astor is designed to allow easy manipulation of Python source via the AST.
+
+
+Getting Started
+---------------
+
+Install with **pip**:
+
+.. code-block:: bash
+
+    $ [sudo] pip install astor
+
+or clone the latest version from GitHub_.
+
+
+Features
+--------
+
+There are some other similar libraries, but astor focuses on the following
+areas:
+
+- Round-trip back to Python via Armin Ronacher's codegen.py module:
+
+  - Modified AST doesn't need linenumbers, ctx, etc. or otherwise be directly
+    compileable
+  - Easy to read generated code as, well, code
+
+- Dump pretty-printing of AST
+
+  - Harder to read than round-tripped code, but more accurate to figure out what
+    is going on.
+
+  - Easier to read than dump from built-in AST module
+
+- Non-recursive treewalk
+
+  - Sometimes you want a recursive treewalk (and astor supports that, starting
+    at any node on the tree), but sometimes you don't need to do that. astor
+    doesn't require you to explicitly visit sub-nodes unless you want to:
+
+  - You can add code that executes before a node's children are visited, and/or
+  - You can add code that executes after a node's children are visited, and/or
+  - You can add code that executes and keeps the node's children from being
+    visited (and optionally visit them yourself via a recursive call)
+
+  - Write functions to access the tree based on object names and/or attribute
+    names
+  - Enjoy easy access to parent node(s) for tree rewriting
+
+
+Functions
+---------
+
+.. note::
+
+   This section is not done. Please look at the source code for all public
+   members.
+
+
+.. function:: to_source(source, indent_with=' ' * 4, \
+                        add_line_information=False))
+
+   Convert a node tree back into Python source code.
+
+   Each level of indentation is replaced with *indent_with*. Per default this
+   parameter is equal to four spaces as suggested by :pep:`8`.
+
+   If *add_line_information* is set to ``True`` comments for the line numbers
+   of the nodes are added to the output. This can be used to spot wrong line
+   number information of statement nodes.
+
+
+.. _GitHub: https://github.com/berkerpeksag/astor/

requirements-dev.txt

@@ -2,3 +2,4 @@ wheel>=0.23.0
 nose>=1.3.0
 tox>=1.7.1
 flake8>=2.1.0
+sphinx-rtd-theme>=0.1.6