Develop

.travis.yml

@@ -0,0 +1,5 @@
+language: python
+python:
+  - "2.7"
+install: "pip install Sphinx"
+script: "make SPHINXOPTS='-W' html"

source/contribute.rst

@@ -0,0 +1,156 @@
+.. |PyPUG| replace:: Python Packaging User Guide
+
+************************
+Contribute to this guide
+************************
+
+The |PyPUG| welcomes contributors! There are lots of ways to help out,
+including:
+
+* Reading the guide and giving feedback
+* Reviewing new contributions
+* Revising existing content
+* Writing new content
+
+Most of the work on the |PyPUG| takes place on the
+`project's GitHub repository`__. To get started, check out the list of
+`open issues`__ and `pull requests`__. If you're planning to write or edit
+the guide, please read the :ref:`style guide <contributing_style_guide>`.
+
+.. __: https://github.com/pypa/python-packaging-user-guide/
+.. __: https://github.com/pypa/python-packaging-user-guide/issues
+.. __: https://github.com/pypa/python-packaging-user-guide/pulls
+
+By contributing to the |PyPUG|, you're expected to follow the Python
+Packaging Authority's `Contributor Code of Conduct`__. Harassment, personal
+attacks, and other unprofessional conduct is not acceptable.
+
+.. __: https://www.pypa.io/en/latest/code-of-conduct/
+
+
+.. _contributing_style_guide:
+
+Style guide
+===========
+
+This style guide has recommendations for how you should write the |PyPUG|.
+Before you start writing, please review it. By following the style guide, your
+contributions will help add to a cohesive whole and make it easier for your
+contributions to be accepted into the project.
+
+
+Purpose
+-------
+
+The purpose of the |PyPUG| is
+
+    to be the authoritative resource on how to package, publish and install
+    Python distributions using current tools
+
+
+Scope
+-----
+
+The guide is meant to answer questions and solve problems with accurate and
+focused recommendations.
+
+The guide isn't meant to be comprehensive and it's not meant to replace
+individual projects' documentation. For example, pip has dozens of commands,
+options, and settings. The pip documentation describes each of them in
+detail, while this guide describes only the parts of pip that are needed to
+complete the specific tasks described in this guide.
+
+
+Audience
+--------
+
+The audience of this guide is anyone who uses Python with packages.
+
+Don't forget that the Python community is big and welcoming. Readers may not
+share your age, gender, educational background, cultural background, and
+more, but they're just as deserving to learn about packaging as you are.
+
+In particular, keep in mind that not all people who use Python see themselves
+as programmers. They might be astronomers or painters or students, not just
+professional software developers.
+
+
+Voice and tone
+--------------
+
+When writing this guide, strive to write with a voice that's approachable
+and humble, even if you have all the answers.
+
+Imagine you're working on a Python project with someone you know to be smart
+and skilled. You like working with them and they like working with you. That
+person has asked you a question. How do you respond? *That* is how you
+should write this guide.
+
+Here's a quick check: try reading aloud to get a sense for your writing's
+voice and tone. Does it sound like something you would say or does it sound
+like you're acting out a part of giving a speech? Feel free to use
+contractions and don't worry about sticking to fussy grammar rules. You are
+hereby granted permission to end a sentence in a preposition.
+
+When writing the guide, adjust your tone for the seriousness and difficulty
+of the topic. If you're writing an introductory tutorial, it's OK to make a
+joke, but if you're covering a sensitive security recommendation, you might
+want to avoid jokes altogether.
+
+
+Conventions and mechanics
+-------------------------
+
+**Write to the reader**
+  When giving recommendations or steps to take, address the reader as *you*
+  or use the imperative mood.
+
+  | Wrong: To install it, the user runs…
+  | Right: You can install it by running…
+  | Right: To install it, run…
+
+**State assumptions**
+  Avoid making unstated assumptions. Reading on the web means that any page of
+  the guide may be the first page of the guide that the reader ever sees.
+  If you're going to make assumptions, then say what assumptions that you're
+  going to make.
+
+**Cross-reference generously**
+  The first time you mention a tool or practice, link to the part of the
+  guide that covers it, or link to a relevant document elsewhere. Save the
+  reader a search.
+
+**Respect naming practices**
+  When naming tools, sites, people, and other proper nouns, use their preferred
+  capitalization.
+
+  | Wrong: Pip uses…
+  | Right: pip uses…
+  |
+  | Wrong: …hosted on github.
+  | Right: …hosted on GitHub.
+
+**Use a gender-neutral style**
+  Often, you'll address the reader directly with *you*, *your* and *yours*.
+  Otherwise, use gender-neutral pronouns *they*, *their*, and *theirs* or
+  avoid pronouns entirely.
+
+  | Wrong: A maintainer uploads the file. Then he…
+  | Right: A maintainer uploads the file. Then they…
+  | Right: A maintainer uploads the file. Then the maintainer…
+
+**Headings**
+  Write headings that use words the reader is searching for. A good way to
+  do this is to have your heading complete an implied question. For example, a
+  reader might want to know *How do I install MyLibrary?* so a good heading
+  might be *Install MyLibrary*.
+
+  In section headings, use sentence case. In other words, write headings as you
+  would write a typical sentence.
+
+  | Wrong: Things You Should Know About Python
+  | Right: Things you should know about Python
+
+**Numbers**
+  In body text, write numbers one through nine as words. For other numbers or
+  numbers in tables, use numerals.

source/index.rst

@@ -16,6 +16,7 @@ This guide is maintained on `github
 .. toctree::
    :maxdepth: 1
 
+   packaging_tutorials
    current
    installing
    distributing
@@ -24,6 +25,7 @@ This guide is maintained on `github
    key_projects
    glossary
    support
+   contribute
 
 
 .. _docs.python.org: http://docs.python.org

source/packaging_tutorials.rst

@@ -0,0 +1,18 @@
+=========================
+Introduction to Packaging
+=========================
+
+:Last Reviewed: Pending
+
+.. note::
+
+   This tutorial is a work in progress. Please see `issue #194`__ for details.
+
+   .. __: https://github.com/pypa/python-packaging-user-guide/issues/194
+
+
+.. toctree::
+   :maxdepth: 1
+
+   prerequisites
+   using-a-virtualenv

source/prerequisites.rst

@@ -0,0 +1,106 @@
+Prerequisites for Creating Packages
+===================================
+
+In order to complete the following tutorial, you must have pip, setuptools
+and wheel installed. The section below describes the steps for installation.
+Please note the latest versions of Python include pip.
+
+
+Install pip, setuptools and wheel
+---------------------------------
+
+To install pip, setuptools and wheel, you must have a version of Python
+installed. You can verify if there is a version of Python in your
+system by entering the following into your terminal or command prompt.
+
+.. code-block:: shell
+
+  python --version
+
+If a version number is returned (for example: python 3.5.0), then
+Python is installed.
+
+Once you have verified a version of Python is installed in your system,
+you may proceed verifying/installing/upgrading pip, setuptools and
+wheel in your system.
+
+
+pip
+----
+
+To verify if pip is installed in your system, enter
+the following into your command prompt.
+
+.. code-block:: shell
+
+  pip --version
+
+If a version number is returned (for example: pip 7.X.X), then
+pip is installed.
+
+If pip is not installed, download get-pip.py from here_.
+
+.. _here: https://bootstrap.pypa.io/get-pip.py
+
+After downloading, run the following command in
+your prompt as this will install pip.
+
+.. code-block:: shell
+
+  python get-pip.py
+
+If pip is installed and needs to be upgraded, enter the following command.
+
+.. code-block:: shell
+
+  pip install --upgrade pip
+
+
+setuptools
+-----------
+
+Once you have verified/upgraded pip in your system, you'll need to
+verify if you have setuptools installed. To verify, enter the following into
+your command prompt and you'll see a list of packages managed by pip.
+
+.. code-block:: shell
+
+  pip list
+
+Scroll through the list, which is listed alphabetically, and locate setuptools.
+
+If setuptools is not installed, enter the following into your command prompt.
+
+.. code-block:: shell
+
+  pip install setuptools
+
+If setuptools needs to be upgraded, enter the following command.
+
+.. code-block:: shell
+
+  pip install --upgrade setuptools
+
+
+wheel
+-----
+
+Similar to setuptools verification, to verify if wheel
+is installed, enter the following and locate wheel.
+
+.. code-block:: shell
+
+  pip list
+
+If wheel is not installed already, enter the following
+into your command prompt.
+
+.. code-block:: shell
+
+  pip install wheel
+
+To upgrade, enter the following into your command prompt.
+
+.. code-block:: shell
+
+  pip install --upgrade wheel