diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/developer-guide.txt | 2 | ||||
| -rw-r--r-- | docs/formats.txt | 6 | ||||
| -rw-r--r-- | docs/history.txt | 8 | ||||
| -rw-r--r-- | docs/index.txt | 1 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 66 | ||||
| -rw-r--r-- | docs/releases.txt | 37 | ||||
| -rw-r--r-- | docs/setuptools.txt | 2 | ||||
| -rw-r--r-- | docs/using.txt | 3 |
9 files changed, 76 insertions, 53 deletions
diff --git a/docs/conf.py b/docs/conf.py index 8be5c3dd..5ea2e05e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,7 +28,7 @@ import setup as setup_script # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['linkify'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -44,7 +44,7 @@ master_doc = 'index' # General information about the project. project = 'Setuptools' -copyright = '2009-2013, The fellowship of the packaging' +copyright = '2009-2014, The fellowship of the packaging' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index 651e6be8..558d6ee7 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -45,7 +45,7 @@ ticket already exists for your issue. If not, create one. Try to think from the perspective of the reader. Explain what behavior you expected, what you got instead, and what factors might have contributed to the unexpected behavior. In Bitbucket, surround a block of code or traceback with the triple -backtick "```" so that it is formatted nicely. +backtick "\`\`\`" so that it is formatted nicely. Filing a ticket provides a forum for justification, discussion, and clarification. The ticket provides a record of the purpose for the change and diff --git a/docs/formats.txt b/docs/formats.txt index 5c461ecb..9e6fe727 100644 --- a/docs/formats.txt +++ b/docs/formats.txt @@ -286,6 +286,12 @@ that can be used to obtain ``Requirement`` objects describing the project's core and optional dependencies. +``setup_requires.txt`` +---------------------- + +Much like ``requires.txt`` except represents the requirements +specified by the ``setup_requires`` parameter to the Distribution. + ``dependency_links.txt`` ------------------------ diff --git a/docs/history.txt b/docs/history.txt new file mode 100644 index 00000000..268137cd --- /dev/null +++ b/docs/history.txt @@ -0,0 +1,8 @@ +:tocdepth: 2 + +.. _changes: + +History +******* + +.. include:: ../CHANGES (links).txt diff --git a/docs/index.txt b/docs/index.txt index 53839bee..d8eb968b 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -16,6 +16,7 @@ Documentation content: .. toctree:: :maxdepth: 2 + history roadmap python3 using diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt index f4a768e4..6c6405a8 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -594,7 +594,7 @@ Requirements Parsing requirement ::= project_name versionspec? extras? versionspec ::= comparison version (',' comparison version)* - comparison ::= '<' | '<=' | '!=' | '==' | '>=' | '>' + comparison ::= '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '===' extras ::= '[' extralist? ']' extralist ::= identifier (',' identifier)* project_name ::= identifier @@ -646,13 +646,10 @@ Requirements Parsing The ``Requirement`` object's version specifiers (``.specs``) are internally sorted into ascending version order, and used to establish what ranges of versions are acceptable. Adjacent redundant conditions are effectively - consolidated (e.g. ``">1, >2"`` produces the same results as ``">1"``, and - ``"<2,<3"`` produces the same results as``"<3"``). ``"!="`` versions are + consolidated (e.g. ``">1, >2"`` produces the same results as ``">2"``, and + ``"<2,<3"`` produces the same results as``"<2"``). ``"!="`` versions are excised from the ranges they fall within. The version being tested for acceptability is then checked for membership in the resulting ranges. - (Note that providing conflicting conditions for the same version (e.g. - ``"<2,>=2"`` or ``"==2,!=2"``) is meaningless and may therefore produce - bizarre results when compared with actual version number(s).) ``__eq__(other_requirement)`` A requirement compares equal to another requirement if they have @@ -681,10 +678,7 @@ Requirements Parsing ``specs`` A list of ``(op,version)`` tuples, sorted in ascending parsed-version order. The `op` in each tuple is a comparison operator, represented as - a string. The `version` is the (unparsed) version number. The relative - order of tuples containing the same version numbers is undefined, since - having more than one operator for a given version is either redundant or - self-contradictory. + a string. The `version` is the (unparsed) version number. Entry Points @@ -967,7 +961,7 @@ version ``ValueError`` is raised. parsed_version - The ``parsed_version`` is a tuple representing a "parsed" form of the + The ``parsed_version`` is an object representing a "parsed" form of the distribution's ``version``. ``dist.parsed_version`` is a shortcut for calling ``parse_version(dist.version)``. It is used to compare or sort distributions by version. (See the `Parsing Utilities`_ section below for @@ -1541,40 +1535,12 @@ Parsing Utilities ----------------- ``parse_version(version)`` - Parse a project's version string, returning a value that can be used to - compare versions by chronological order. Semantically, the format is a - rough cross between distutils' ``StrictVersion`` and ``LooseVersion`` - classes; if you give it versions that would work with ``StrictVersion``, - then they will compare the same way. Otherwise, comparisons are more like - a "smarter" form of ``LooseVersion``. It is *possible* to create - pathological version coding schemes that will fool this parser, but they - should be very rare in practice. - - The returned value will be a tuple of strings. Numeric portions of the - version are padded to 8 digits so they will compare numerically, but - without relying on how numbers compare relative to strings. Dots are - dropped, but dashes are retained. Trailing zeros between alpha segments - or dashes are suppressed, so that e.g. "2.4.0" is considered the same as - "2.4". Alphanumeric parts are lower-cased. - - The algorithm assumes that strings like "-" and any alpha string that - alphabetically follows "final" represents a "patch level". So, "2.4-1" - is assumed to be a branch or patch of "2.4", and therefore "2.4.1" is - considered newer than "2.4-1", which in turn is newer than "2.4". - - Strings like "a", "b", "c", "alpha", "beta", "candidate" and so on (that - come before "final" alphabetically) are assumed to be pre-release versions, - so that the version "2.4" is considered newer than "2.4a1". Any "-" - characters preceding a pre-release indicator are removed. (In versions of - setuptools prior to 0.6a9, "-" characters were not removed, leading to the - unintuitive result that "0.2-rc1" was considered a newer version than - "0.2".) - - Finally, to handle miscellaneous cases, the strings "pre", "preview", and - "rc" are treated as if they were "c", i.e. as though they were release - candidates, and therefore are not as new as a version string that does not - contain them. And the string "dev" is treated as if it were an "@" sign; - that is, a version coming before even "a" or "alpha". + Parsed a project's version string as defined by PEP 440. The returned + value will be an object that represents the version. These objects may + be compared to each other and sorted. The sorting algorithm is as defined + by PEP 440 with the addition that any version which is not a valid PEP 440 + version will be considered less than any valid PEP 440 version and the + invalid versions will continue sorting using the original algorithm. .. _yield_lines(): @@ -1629,10 +1595,12 @@ Parsing Utilities See ``to_filename()``. ``safe_version(version)`` - Similar to ``safe_name()`` except that spaces in the input become dots, and - dots are allowed to exist in the output. As with ``safe_name()``, if you - are generating a filename from this you should replace any "-" characters - in the output with underscores. + This will return the normalized form of any PEP 440 version, if the version + string is not PEP 440 compatible than it is similar to ``safe_name()`` + except that spaces in the input become dots, and dots are allowed to exist + in the output. As with ``safe_name()``, if you are generating a filename + from this you should replace any "-" characters in the output with + underscores. ``safe_extra(extra)`` Return a "safe" form of an extra's name, suitable for use in a requirement diff --git a/docs/releases.txt b/docs/releases.txt index 66c0896f..a9742c20 100644 --- a/docs/releases.txt +++ b/docs/releases.txt @@ -17,6 +17,43 @@ revision slated for release:: python -m jaraco.packaging.release +Bootstrap Bookmark +------------------ + +Setuptools has a bootstrap script (ez_setup.py) which is hosted in the +repository and must be updated with each release (to bump the default version). +The "published" version of the script is the one indicated by the ``bootstrap`` +bookmark (Mercurial) or branch (Git). + +Therefore, the latest bootstrap script can be retrieved by checking out the +repository at that bookmark. It's also possible to get the bootstrap script for +any particular release by grabbing the script from that tagged release. + +The officially-published location of the bootstrap script is hosted on Python +infrastructure (#python-infra on freenode) at https://bootstrap.pypa.io and +is updated every fifteen minutes from the bootstrap script. Sometimes, +especially when the bootstrap script is rolled back, this +process doesn't work as expected and requires manual intervention. + +Release Frequency +----------------- + +Some have asked why Setuptools is released so frequently. Because Setuptools +uses a mechanical release process, it's very easy to make releases whenever the +code is stable (tests are passing). As a result, the philosophy is to release +early and often. + +While some find the frequent releases somewhat surprising, they only empower +the user. Although releases are made frequently, users can choose the frequency +at which they use those releases. If instead Setuptools contributions were only +released in batches, the user would be constrained to only use Setuptools when +those official releases were made. With frequent releases, the user can govern +exactly how often he wishes to update. + +Frequent releases also then obviate the need for dev or beta releases in most +cases. Because releases are made early and often, bugs are discovered and +corrected quickly, in many cases before other users have yet to encounter them. + Release Managers ---------------- diff --git a/docs/setuptools.txt b/docs/setuptools.txt index a34ec304..89c08e23 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -308,7 +308,7 @@ unless you need the associated ``setuptools`` feature. (Note: projects listed in ``setup_requires`` will NOT be automatically installed on the system where the setup script is being run. They are - simply downloaded to the setup directory if they're not locally available + simply downloaded to the ./.eggs directory if they're not locally available already. If you want them to be installed, as well as being available when the setup script is run, you should add them to ``install_requires`` **and** ``setup_requires``.) diff --git a/docs/using.txt b/docs/using.txt index e44847d6..bd80893d 100644 --- a/docs/using.txt +++ b/docs/using.txt @@ -8,3 +8,6 @@ it at the very beginning of `setup.py` like this:: from ez_setup import use_setuptools use_setuptools() + +More info on `ez_setup.py` can be found at `the project home page +<https://pypy.python.org/pypi/setuptools>`_. |