getting started

docs/contents.rst.inc

@@ -1,5 +1,64 @@
-stuff.
+Getting Started
+---------------
+
+This part of the guide focuses on setting up your Python environment.
+
+.. toctree::
+   :maxdepth: 2
+
+
+
+- Properly Install Python
+
+
+
+Writing Great Code
+------------------
+
+This part of the guide focuses on best practices for writing Python code.
 
 
 
 
+Scenario Guide
+--------------
+
+This part of the guide focuses on tool and module advice based on
+different scenarios.
+
+
+
+
+Shipping Great Code
+-------------------
+
+This part of the guide focuses on deploying your Python code.
+
+
+
+Development Environment
+-----------------------
+
+
+
+
+Additional Notes
+----------------
+
+This part of the guide, which is mostly prose, begins with some
+background information about Python, then focuses on next steps.
+
+
+
+
+
+--------------------------------------
+
+Contibution notes and legal information are here (for those interested).
+
+.. toctree::
+   :maxdepth: 2
+
+   notes/contribute
+   notes/license
+   notes/styleguide

docs/notes/contribute.rst

@@ -0,0 +1,27 @@
+Contribute
+~~~~~~~~~~
+
+Python-guide is under active development, and contributors are welcome.
+
+If you have a feature request, suggestion, or bug report, please open a new
+issue on GitHub_. To submit patches, please send a pull request on GitHub_.
+Once your changes get merged back in, you'll automatically be added to the
+`Contributors List <https://github.com/kennethreitz/python-guide/contributors>`_.
+
+Style Guide
+-----------
+
+For all contributions, please follow the :ref:`guide-style-guide`.
+
+.. _todo-list-ref:
+
+Todo List
+---------
+
+If you'd like to contribute, there's plenty to do. Here's a short todo_ list.
+
+    .. include:: ../../TODO.rst
+
+
+.. _GitHub: http://github.com/kennethreitz/python-guide/
+.. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst

docs/notes/license.rst

@@ -0,0 +1,4 @@
+License
+-------
+
+.. todo:: Determine License

docs/notes/styleguide.rst

@@ -0,0 +1,164 @@
+.. _guide-style-guide:
+
+=====================
+The Guide Style Guide
+=====================
+
+As with all documentation, having a consistent formating helps make the
+document more understandable. In order to make The Guide easier to digest,
+all contributions should fit within the rules of this style guide where
+appropriate.
+
+The Guide is written as :ref:`restructuredtext-ref`.
+
+.. note:: Parts of The Guide may not yet match this style guide. Feel free
+   to update those parts to be in sync with The Guide Style Guide
+
+.. note:: On any page of the rendered HTML you can click "Show Source" to
+   see how authors have styled the page.
+
+Relevancy
+---------
+
+Strive to keep any contributions relevant to the :ref:`purpose of The Guide
+<about-ref>`.
+
+* Avoid including too much information on subjects that don't directly
+  relate to Python development.
+* Prefer to link to other sources if the information is already out there.
+  Be sure to describe what and why you are linking.
+* `Cite <http://sphinx.pocoo.org/rest.html?highlight=citations#citations>`_
+  references where needed.
+* If a subject isn't directly relevant to Python, but useful in conjunction
+  with Python (ex: Git, Github, Databases), reference by linking to useful
+  resources and describe why it's useful to Python.
+* When in doubt, ask.
+
+Headings
+--------
+
+Use the following styles for headings.
+
+Chapter title::
+
+    #########
+    Chapter 1
+    #########
+
+Page title::
+
+    ===================
+    Time is an Illusion
+    ===================
+
+Section headings::
+
+    Lunchtime Doubly So
+    -------------------
+
+Sub section headings::
+
+    Very Deep
+    ~~~~~~~~~
+
+Prose
+-----
+
+Wrap text lines at 78 characters. Where necessary, lines may exceed 78
+characters, especially if wrapping would make the source text more difficult
+to read.
+
+
+Code Examples
+-------------
+
+Wrap all code examples at 70 characters to avoid horizontal scrollbars.
+
+Command line examples::
+
+    .. code-block:: console
+
+        $ run command --help
+        $ ls ..
+
+Be sure to include the ``$`` prefix before each line.
+
+Python interpreter examples::
+
+    Label the example::
+
+    .. code-block:: python
+
+        >>> import this
+
+Python examples::
+
+    Descriptive title::
+
+    .. code-block:: python
+
+        def get_answer():
+            return 42
+
+Externally Linking
+------------------
+
+* Prefer labels for well known subjects (ex: proper nouns) when linking::
+
+    Sphinx_ is used to document Python.
+
+    .. _Sphinx: http://sphinx.pocoo.org
+
+* Prefer to use descriptive labels with inline links instead of leaving bare
+  links::
+
+    Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_
+
+* Avoid using labels such as "click here", "this", etc. preferring
+  descriptive labels (SEO worthy) instead.
+
+Linking to Sections in The Guide
+--------------------------------
+
+To cross-reference other parts of this documentation, use the `:ref:
+<http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
+keyword and labels.
+
+To make reference labels more clear and unique, always add a ``-ref`` suffix::
+
+    .. _some-section-ref:
+
+    Some Section
+    ------------
+
+Notes and Warnings
+------------------
+
+Make use of the appropriate `admonitions directives
+<http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
+
+Notes::
+
+    .. note::
+        The Hitchhiker’s Guide to the Galaxy has a few things to say
+        on the subject of towels. A towel, it says, is about the most
+        massively useful thing an interstellar hitch hiker can have.
+
+Warnings::
+
+    .. warning:: DON'T PANIC
+
+TODOs
+-----
+
+Please mark any incomplete areas of The Guide with a `todo directive
+<http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To
+avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub
+documents or large incomplete sections.
+
+::
+
+    .. todo::
+        Learn the Ultimate Answer to the Ultimate Question
+        of Life, The Universe, and Everything
+