diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 57 | ||||
| -rw-r--r-- | docs/developer-guide.txt | 22 | ||||
| -rw-r--r-- | docs/development.txt | 1 | ||||
| -rw-r--r-- | docs/index.txt | 2 | ||||
| -rw-r--r-- | docs/merge-faq.txt | 80 | ||||
| -rw-r--r-- | docs/merge.txt | 122 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 2 | ||||
| -rw-r--r-- | docs/python3.txt | 74 | ||||
| -rw-r--r-- | docs/setuptools.txt | 20 | ||||
| -rw-r--r-- | docs/using.txt | 13 |
10 files changed, 111 insertions, 282 deletions
diff --git a/docs/conf.py b/docs/conf.py index 5ea2e05e..c2a63873 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 = ['linkify'] +extensions = ['rst.linker'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -198,3 +198,58 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +link_files = { + 'CHANGES.txt': dict( + using=dict( + BB='https://bitbucket.org', + GH='https://github.com', + ), + replace=[ + dict( + pattern=r"(Issue )?#(?P<issue>\d+)", + url='{BB}/pypa/setuptools/issue/{issue}', + ), + dict( + pattern=r"Pull Request ?#(?P<pull_request>\d+)", + url='{BB}/pypa/setuptools/pull-request/{pull_request}', + ), + dict( + pattern=r"Distribute #(?P<distribute>\d+)", + url='{BB}/tarek/distribute/issue/{distribute}', + ), + dict( + pattern=r"Buildout #(?P<buildout>\d+)", + url='{GH}/buildout/buildout/issues/{buildout}', + ), + dict( + pattern=r"Old Setuptools #(?P<old_setuptools>\d+)", + url='http://bugs.python.org/setuptools/issue{old_setuptools}', + ), + dict( + pattern=r"Jython #(?P<jython>\d+)", + url='http://bugs.jython.org/issue{jython}', + ), + dict( + pattern=r"Python #(?P<python>\d+)", + url='http://bugs.python.org/issue{python}', + ), + dict( + pattern=r"Interop #(?P<interop>\d+)", + url='{GH}/pypa/interoperability-peps/issues/{interop}', + ), + dict( + pattern=r"Pip #(?P<pip>\d+)", + url='{GH}/pypa/pip/issues/{pip}', + ), + dict( + pattern=r"Packaging #(?P<packaging>\d+)", + url='{GH}/pypa/packaging/issues/{packaging}', + ), + dict( + pattern=r"[Pp]ackaging (?P<packaging_ver>\d+(\.\d+)+)", + url='{GH}/pypa/packaging/blob/{packaging_ver}/CHANGELOG.rst', + ), + ], + ), +} diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt index 558d6ee7..ae33649b 100644 --- a/docs/developer-guide.txt +++ b/docs/developer-guide.txt @@ -92,9 +92,10 @@ Testing The primary tests are run using py.test. To run the tests:: - $ python setup.py ptr + $ python setup.py test -Or install py.test into your environment and run ``py.test``. +Or install py.test into your environment and run ``PYTHONPATH=. py.test`` +or ``python -m pytest``. Under continuous integration, additional tests may be run. See the ``.travis.yml`` file for full details on the tests run under Travis-CI. @@ -109,3 +110,20 @@ Setuptools follows ``semver`` with some exceptions: - Omits 'v' prefix for tags. .. explain value of reflecting meaning in versions. + +---------------------- +Building Documentation +---------------------- + +Setuptools relies on the Sphinx system for building documentation and in +particular the ``build_sphinx`` distutils command. To build the +documentation, invoke:: + + python setup.py build_sphinx + +from the root of the repository. Setuptools will download a compatible +build of Sphinx and any requisite plugins and then build the +documentation in the build/sphinx directory. + +Setuptools does not support invoking the doc builder from the docs/ +directory as some tools expect. diff --git a/docs/development.txt b/docs/development.txt index 6fe30f6e..455f038a 100644 --- a/docs/development.txt +++ b/docs/development.txt @@ -33,4 +33,3 @@ setuptools changes. You have been warned. developer-guide formats releases - diff --git a/docs/index.txt b/docs/index.txt index d8eb968b..6ac37252 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -19,9 +19,7 @@ Documentation content: history roadmap python3 - using setuptools easy_install pkg_resources development - merge diff --git a/docs/merge-faq.txt b/docs/merge-faq.txt deleted file mode 100644 index ea45f30c..00000000 --- a/docs/merge-faq.txt +++ /dev/null @@ -1,80 +0,0 @@ -Setuptools/Distribute Merge FAQ -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -How do I upgrade from Distribute? -================================= - -Distribute specifically prohibits installation of Setuptools 0.7 from Distribute 0.6. There are then two options for upgrading. - -Note that after upgrading using either technique, the only option to downgrade to either version is to completely uninstall Distribute and Setuptools 0.7 versions before reinstalling an 0.6 release. - -Use Distribute 0.7 ------------------- - -The PYPA has put together a compatibility wrapper, a new release of Distribute version 0.7. This package will install over Distribute 0.6.x installations and will replace Distribute with a simple wrapper that requires Setuptools 0.7 or later. This technique is experimental, but initial results indicate this technique is the easiest upgrade path. - - -Uninstall ---------- - -First, completely uninstall Distribute. Since Distribute does not have an automated installation routine, this process is manual. Follow the instructions in the README for uninstalling. - - -How do I upgrade from Setuptools 0.6? -===================================== - -There are no special instructions for upgrading over older versions of Setuptools. Simply use `easy_install -U` or run the latest `ez_setup.py`. - -Where does the merge occur? -======================================================== - -The merge is occurring between the heads of the default branch of Distribute and the setuptools-0.6 branch of Setuptools. The Setuptools SVN repo has been converted to a Mercurial repo hosted on Bitbucket. The work is still underway, so the exact changesets included may change, although the anticipated merge targets are Setuptools at 0.6c12 and Distribute at 0.6.35. - -What happens to other branches? -======================================================== - -Distribute 0.7 was abandoned long ago and won't be included in the resulting code tree, but may be retained for posterity in the original repo. - -Setuptools default branch (also 0.7 development) may also be abandoned or may be incorporated into the new merged line if desirable (and as resources allow). - -What history is lost/changed? -======================================================== - -As setuptools was not on Mercurial when the fork occurred and as Distribute did not include the full setuptools history (prior to the creation of the setuptools-0.6 branch), the two source trees were not compatible. In order to most effectively communicate the code history, the Distribute code was grafted onto the (originally private) setuptools Mercurial repo. Although this grafting maintained the full code history with names, dates, and changes, it did lose the original hashes of those changes. Therefore, references to changes by hash (including tags) are lost. - -Additionally, any heads that were not actively merged into the Distribute 0.6.35 release were also omitted. As a result, the changesets included in the merge repo are those from the original setuptools repo and all changesets ancestral to the Distribute 0.6.35 release. - -What features will be in the merged code base? -======================================================== - -In general, all "features" added in distribute will be included in setuptools. Where there exist conflicts or undesirable features, we will be explicit about what these limitations are. Changes that are backward-incompatible from setuptools 0.6 to distribute will likely be removed, and these also will be well documented. - -Bootstrapping scripts (ez_setup/distribute_setup) and docs, as with distribute, will be maintained in the repository and built as part of the release process. Documentation and bootstrapping scripts will be hosted at python.org, as they are with distribute now. Documentation at telecommunity will be updated to refer or redirect to the new, merged docs. - -On the whole, the merged setuptools should be largely compatible with the latest releases of both setuptools and distribute and will be an easy transition for users of either library. - -Who is invited to contribute? Who is excluded? -======================================================== - -While we've worked privately to initiate this merge due to the potential sensitivity of the topic, no one is excluded from this effort. We invite all members of the community, especially those most familiar with Python packaging and its challenges to join us in the effort. - -We have lots of ideas for how we'd like to improve the codebase, release process, everything. Like distribute, the post-merge setuptools will have its source hosted on Bitbucket. (So if you're currently a distribute contributor, about the only thing that's going to change is the URL of the repository you follow.) Also like distribute, it'll support Python 3, and hopefully we'll soon merge Vinay Sajip's patches to make it run on Python 3 without needing 2to3 to be run on the code first. - -While we've worked privately to initiate this merge due to the potential sensitivity of the topic, no one is excluded from this effort. We invite all members of the community, especially those most familiar with Python packaging and its challenges to join us in the effort. - -Why Setuptools and not Distribute or another name? -======================================================== - -We do, however, understand that this announcement might be unsettling for some. The setuptools name has been subjected to a lot of deprecation in recent years, so the idea that it will now be the preferred name instead of distribute might be somewhat difficult or disorienting for some. We considered use of another name (Distribute or an entirely new name), but that would serve to only complicate matters further. Instead, our goal is to simplify the packaging landscape but without losing any hard-won advancements. We hope that the people who worked to spread the first message will be equally enthusiastic about spreading the new one, and we especially look forward to seeing the new posters and slogans celebrating setuptools. - -What is the timeframe of release? -======================================================== - -There are no hard timeframes for any of this effort, although progress is underway and a draft merge is underway and being tested privately. As an unfunded volunteer effort, our time to put in on it is limited, and we've both had some recent health and other challenges that have made working on this difficult, which in part explains why we haven't met our original deadline of a completed merge before PyCon. - -The final Setuptools 0.7 was cut on June 1, 2013 and will be released to PyPI shortly thereafter. - -What version number can I expect for the new release? -======================================================== - -The new release will roughly follow the previous trend for setuptools and release the new release as 0.7. This number is somewhat arbitrary, but we wanted something other than 0.6 to distinguish it from its ancestor forks but not 1.0 to avoid putting too much emphasis on the release itself and to focus on merging the functionality. In the future, the project will likely adopt a versioning scheme similar to semver to convey semantic meaning about the release in the version number. diff --git a/docs/merge.txt b/docs/merge.txt deleted file mode 100644 index ba37d6e4..00000000 --- a/docs/merge.txt +++ /dev/null @@ -1,122 +0,0 @@ -Merge with Distribute -~~~~~~~~~~~~~~~~~~~~~ - -In 2013, the fork of Distribute was merged back into Setuptools. This -document describes some of the details of the merge. - -.. toctree:: - :maxdepth: 2 - - merge-faq - -Process -======= - -In order to try to accurately reflect the fork and then re-merge of the -projects, the merge process brought both code trees together into one -repository and grafted the Distribute fork onto the Setuptools development -line (as if it had been created as a branch in the first place). - -The rebase to get distribute onto setuptools went something like this:: - - hg phase -d -f -r 26b4c29b62db - hg rebase -s 26b4c29b62db -d 7a5cf59c78d7 - -The technique required a late version of mercurial (2.5) to work correctly. - -The only code that was included was the code that was ancestral to the public -releases of Distribute 0.6. Additionally, because Setuptools was not hosted -on Mercurial at the time of the fork and because the Distribute fork did not -include a complete conversion of the Setuptools history, the Distribute -changesets had to be re-applied to a new, different conversion of the -Setuptools SVN repository. As a result, all of the hashes have changed. - -Distribute was grafted in a 'distribute' branch and the 'setuptools-0.6' -branch was targeted for the merge. The 'setuptools' branch remains with -unreleased code and may be incorporated in the future. - -Reconciling Differences -======================= - -There were both technical and philosophical differences between Setuptools -and Distribute. To reconcile these differences in a manageable way, the -following technique was undertaken: - -Create a 'Setuptools-Distribute merge' branch, based on a late release of -Distribute (0.6.35). This was done with a00b441856c4. - -In that branch, first remove code that is no longer relevant to -Setuptools (such as the setuptools patching code). - -Next, in the the merge branch, create another base from at the point where the -fork occurred (such that the code is still essentially an older but pristine -setuptools). This base can be found as 955792b069d0. This creates two heads -in the merge branch, each with a basis in the fork. - -Then, repeatedly copy changes for a -single file or small group of files from a late revision of that file in the -'setuptools-0.6' branch (1aae1efe5733 was used) and commit those changes on -the setuptools-only head. That head is then merged with the head with -Distribute changes. It is in this Mercurial -merge operation that the fundamental differences between Distribute and -Setuptools are reconciled, but since only a single file or small set of files -are used, the scope is limited. - -Finally, once all the challenging files have been reconciled and merged, the -remaining changes from the setuptools-0.6 branch are merged, deferring to the -reconciled changes (a1fa855a5a62 and 160ccaa46be0). - -Originally, jaraco attempted all of this using anonymous heads in the -Distribute branch, but later realized this technique made for a somewhat -unclear merge process, so the changes were re-committed as described above -for clarity. In this way, the "distribute" and "setuptools" branches can -continue to track the official Distribute changesets. - -Concessions -=========== - -With the merge of Setuptools and Distribute, the following concessions were -made: - -Differences from setuptools 0.6c12: - -Major Changes -------------- - -* Python 3 support. -* Improved support for GAE. -* Support `PEP-370 <http://www.python.org/dev/peps/pep-0370/>`_ per-user site - packages. -* Sort order of Distributions in pkg_resources now prefers PyPI to external - links (Distribute issue 163). -* Python 2.4 or greater is required (drop support for Python 2.3). - -Minor Changes -------------- - -* Wording of some output has changed to replace contractions with their - canonical form (i.e. prefer "could not" to "couldn't"). -* Manifest files are only written for 32-bit .exe launchers. - -Differences from Distribute 0.6.36: - -Major Changes -------------- - -* The _distribute property of the setuptools module has been removed. -* Distributions are once again installed as zipped eggs by default, per the - rationale given in `the seminal bug report - <http://bugs.python.org/setuptools/issue33>`_ indicates that the feature - should remain and no substantial justification was given in the `Distribute - report <https://bitbucket.org/tarek/distribute/issue/19/>`_. - -Minor Changes -------------- - -* The patch for `#174 <https://bitbucket.org/tarek/distribute/issue/174>`_ - has been rolled-back, as the comment on the ticket indicates that the patch - addressed a symptom and not the fundamental issue. -* ``easy_install`` (the command) once again honors setup.cfg if found in the - current directory. The "mis-behavior" characterized in `#99 - <https://bitbucket.org/tarek/distribute/issue/99>`_ is actually intended - behavior, and no substantial rationale was given for the deviation. diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt index 6c6405a8..3d40a1a2 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -592,7 +592,7 @@ Requirements Parsing The syntax of a requirement specifier can be defined in EBNF as follows:: - requirement ::= project_name versionspec? extras? + requirement ::= project_name extras? versionspec? versionspec ::= comparison version (',' comparison version)* comparison ::= '<' | '<=' | '!=' | '==' | '>=' | '>' | '~=' | '===' extras ::= '[' extralist? ']' diff --git a/docs/python3.txt b/docs/python3.txt index df173000..d550cb68 100644 --- a/docs/python3.txt +++ b/docs/python3.txt @@ -5,16 +5,22 @@ Supporting both Python 2 and Python 3 with Setuptools Starting with Distribute version 0.6.2 and Setuptools 0.7, the Setuptools project supported Python 3. Installing and using setuptools for Python 3 code works exactly the same as for Python 2 -code, but Setuptools also helps you to support Python 2 and Python 3 from -the same source code by letting you run 2to3 on the code as a part of the -build process, by setting the keyword parameter ``use_2to3`` to True. +code. +Setuptools provides a facility to invoke 2to3 on the code as a part of the +build process, by setting the keyword parameter ``use_2to3`` to True, but +the Setuptools strongly recommends instead developing a unified codebase +using `six <https://pypi.python.org/pypi/six>`_, +`future <https://pypi.python.org/pypi/future>`_, or another compatibility +library. -Setuptools as help during porting -================================= -Setuptools can make the porting process much easier by automatically running -2to3 as a part of the test running. To do this you need to configure the +Using 2to3 +========== + +Setuptools attempts to make the porting process easier by automatically +running +2to3 as a part of running tests. To do so, you need to configure the setup.py so that you can run the unit tests with ``python setup.py test``. See :ref:`test` for more information on this. @@ -37,23 +43,23 @@ to a list of names of packages containing fixers. To exclude fixers, the parameter ``use_2to3_exclude_fixers`` can be set to fixer names to be skipped. -A typical setup.py can look something like this:: +An example setup.py might look something like this:: from setuptools import setup setup( name='your.module', - version = '1.0', + version='1.0', description='This is your awesome module', author='You', author_email='your@email', - package_dir = {'': 'src'}, - packages = ['your', 'you.module'], - test_suite = 'your.module.tests', - use_2to3 = True, - convert_2to3_doctests = ['src/your/module/README.txt'], - use_2to3_fixers = ['your.fixers'], - use_2to3_exclude_fixers = ['lib2to3.fixes.fix_import'], + package_dir={'': 'src'}, + packages=['your', 'you.module'], + test_suite='your.module.tests', + use_2to3=True, + convert_2to3_doctests=['src/your/module/README.txt'], + use_2to3_fixers=['your.fixers'], + use_2to3_exclude_fixers=['lib2to3.fixes.fix_import'], ) Differential conversion @@ -86,39 +92,3 @@ Advanced features If you don't want to run the 2to3 conversion on the doctests in Python files, you can turn that off by setting ``setuptools.use_2to3_on_doctests = False``. - -Note on compatibility with older versions of setuptools -======================================================= - -Setuptools earlier than 0.7 does not know about the new keyword parameters to -support Python 3. -As a result it will warn about the unknown keyword parameters if you use -those versions of setuptools instead of Distribute under Python 2. This output -is not an error, and -install process will continue as normal, but if you want to get rid of that -error this is easy. Simply conditionally add the new parameters into an extra -dict and pass that dict into setup():: - - from setuptools import setup - import sys - - extra = {} - if sys.version_info >= (3,): - extra['use_2to3'] = True - extra['convert_2to3_doctests'] = ['src/your/module/README.txt'] - extra['use_2to3_fixers'] = ['your.fixers'] - - setup( - name='your.module', - version = '1.0', - description='This is your awesome module', - author='You', - author_email='your@email', - package_dir = {'': 'src'}, - packages = ['your', 'you.module'], - test_suite = 'your.module.tests', - **extra - ) - -This way the parameters will only be used under Python 3, where Distribute or -Setuptools 0.7 or later is required. diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 89c08e23..d6a62de8 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -112,10 +112,16 @@ the distutils. Here's a minimal setup script using setuptools:: ) As you can see, it doesn't take much to use setuptools in a project. -Just by doing the above, this project will be able to produce eggs, upload to +Run that script in your project folder, alongside the Python packages +you have developed. + +Invoke that script to produce eggs, upload to PyPI, and automatically include all packages in the directory where the setup.py lives. See the `Command Reference`_ section below to see what -commands you can give to this setup script. +commands you can give to this setup script. For example, +to produce a source distribution, simply invoke:: + + python setup.py sdist Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your @@ -1467,7 +1473,7 @@ are included in any source distribution you build. This is a big improvement over having to manually write a ``MANIFEST.in`` file and try to keep it in sync with your project. So, if you are using CVS or Subversion, and your source distributions only need to include files that you're tracking in -revision control, don't create a a ``MANIFEST.in`` file for your project. +revision control, don't create a ``MANIFEST.in`` file for your project. (And, if you already have one, you might consider deleting it the next time you would otherwise have to change it.) @@ -2595,8 +2601,8 @@ those methods' docstrings for more details. Adding Support for Other Revision Control Systems ------------------------------------------------- -If you would like to create a plugin for ``setuptools`` to find files in other -source control systems besides CVS and Subversion, you can do so by adding an +If you would like to create a plugin for ``setuptools`` to find files in +source control systems, you can do so by adding an entry point to the ``setuptools.file_finders`` group. The entry point should be a function accepting a single directory name, and should yield all the filenames within that directory (and any subdirectories thereof) that @@ -2652,9 +2658,7 @@ Subclassing ``Command`` ----------------------- Sorry, this section isn't written yet, and neither is a lot of what's below -this point, except for the change log. You might want to `subscribe to changes -in this page <setuptools?action=subscribe>`_ to see when new documentation is -added or updated. +this point. XXX diff --git a/docs/using.txt b/docs/using.txt deleted file mode 100644 index bd80893d..00000000 --- a/docs/using.txt +++ /dev/null @@ -1,13 +0,0 @@ -================================ -Using Setuptools in your project -================================ - -To use Setuptools in your project, the recommended way is to ship -`ez_setup.py` alongside your `setup.py` script and call -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>`_. |