diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 79c13b8..c24764f 100644 --- a/docs/contents.rst.inc +++ b/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 diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst new file mode 100644 index 0000000..0d709f2 --- /dev/null +++ b/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 `_. + +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 diff --git a/docs/notes/license.rst b/docs/notes/license.rst new file mode 100644 index 0000000..d26b3c7 --- /dev/null +++ b/docs/notes/license.rst @@ -0,0 +1,4 @@ +License +------- + +.. todo:: Determine License \ No newline at end of file diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst new file mode 100644 index 0000000..edaecc1 --- /dev/null +++ b/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 +`. + +* 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 `_ + 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 `_ + +* 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: +`_ +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 +`_ 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 +`_. 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 +