Stripped leading 'sec:' from all section labels -- generates bad filenames,
bad link URLs in HTML, etc.
This commit is contained in:
Greg Ward
parent
e9792c4563
commit
e78298a6bd
|
|
@ -15,7 +15,7 @@
|
|||
\tableofcontents
|
||||
|
||||
\section{Introduction}
|
||||
\label{sec:intro}
|
||||
\label{intro}
|
||||
|
||||
In the past, Python module developers have not had much infrastructure
|
||||
support for distributing modules, nor have Python users had much support
|
||||
|
|
@ -38,7 +38,7 @@ refer to the ``Installing Python Modules'' manual.
|
|||
|
||||
|
||||
\section{Concepts \& Terminology}
|
||||
\label{sec:concepts}
|
||||
\label{concepts}
|
||||
|
||||
Using the Distutils is quite simple, both for module developers and for
|
||||
users/administrators installing third-party modules. As a developer,
|
||||
|
|
@ -65,7 +65,7 @@ of code.
|
|||
|
||||
|
||||
\subsection{A simple example}
|
||||
\label{sec:simple-example}
|
||||
\label{simple-example}
|
||||
|
||||
The setup script is usually quite simple, although since it's written in
|
||||
Python, there are no arbitrary limits to what you can do. If all you
|
||||
|
|
@ -140,7 +140,7 @@ Other \command{bdist\_*} commands exist for RPM-based Linux systems
|
|||
|
||||
|
||||
\subsection{General Python terminology}
|
||||
\label{sec:python-terms}
|
||||
\label{python-terms}
|
||||
|
||||
If you're reading this document, you probably have a good idea of what
|
||||
modules, extensions, and so forth are. Nevertheless, just to be sure
|
||||
|
|
@ -167,7 +167,7 @@ following glossary of common Python terms:
|
|||
|
||||
|
||||
\subsection{Distutils-specific terminology}
|
||||
\label{sec:distutils-term}
|
||||
\label{distutils-term}
|
||||
|
||||
The following terms apply more specifically to the domain of
|
||||
distributing Python modules using the Distutils:
|
||||
|
|
@ -192,13 +192,13 @@ distributing Python modules using the Distutils:
|
|||
|
||||
|
||||
\section{Writing the Setup Script}
|
||||
\label{sec:setup-script}
|
||||
\label{setup-script}
|
||||
|
||||
The setup script is the centre of all activity in building,
|
||||
distributing, and installing modules using the Distutils. The main
|
||||
purpose of the setup script is to describe your module distribution to
|
||||
the Distutils, so that the various commands that operate on your modules
|
||||
do the right thing. As we saw in section~\ref{sec:simple-example}
|
||||
do the right thing. As we saw in section~\ref{simple-example}
|
||||
above, the setup script consists mainly of a call to \function{setup()},
|
||||
and all information supplied to the Distutils is suppled as keyword
|
||||
arguments to \function{setup()}.
|
||||
|
|
@ -225,7 +225,7 @@ setup (name = "Distutils",
|
|||
)
|
||||
\end{verbatim}
|
||||
There are only two differences between this and the trivial one-file
|
||||
distribution presented in section~\ref{sec:simple-example}: more
|
||||
distribution presented in section~\ref{simple-example}: more
|
||||
meta-data, and the specification of pure Python modules by package,
|
||||
rather than by module. This is important since the Distutils consist of
|
||||
a couple of dozen modules split into (so far) two packages; an explicit
|
||||
|
|
@ -245,7 +245,7 @@ the opposite of the Mac OS convention with colons).
|
|||
|
||||
|
||||
\subsection{Package directories}
|
||||
\label{sec:package-dirs}
|
||||
\label{package-dirs}
|
||||
|
||||
The \option{packages} option tells the Distutils to process (build,
|
||||
distribute, install, etc.) all pure Python modules found in each package
|
||||
|
|
@ -292,12 +292,12 @@ tells the Distutils to look for \file{lib/\_\_init\_\_.py} and
|
|||
|
||||
|
||||
\subsection{Listing individual modules}
|
||||
\label{sec:listing-modules}
|
||||
\label{listing-modules}
|
||||
|
||||
For a small module distribution, you might prefer to list all modules
|
||||
rather than listing packages---especially the case of a single module
|
||||
that goes in the ``root package'' (i.e., no package at all). This
|
||||
simplest case was shown in section~\ref{sec:simple-example}; here is a
|
||||
simplest case was shown in section~\ref{simple-example}; here is a
|
||||
slightly more involved example:
|
||||
\begin{verbatim}
|
||||
py_modules = ['mod1', 'pkg.mod2']
|
||||
|
|
@ -312,7 +312,7 @@ And again, you can override the package/directory layout using the
|
|||
|
||||
|
||||
\section{Writing the Setup Configuration File}
|
||||
\label{sec:setup-config}
|
||||
\label{setup-config}
|
||||
|
||||
\XXX{not implemented yet!}
|
||||
|
||||
|
|
@ -338,9 +338,9 @@ setup configuration file, \file{setup.cfg}.
|
|||
|
||||
|
||||
\section{Creating a Source Distribution}
|
||||
\label{sec:source-dist}
|
||||
\label{source-dist}
|
||||
|
||||
As shown in section~\ref{sec:simple-example}, you use the
|
||||
As shown in section~\ref{simple-example}, you use the
|
||||
\command{sdist} command to create a source distribution. In the
|
||||
simplest case,
|
||||
\begin{verbatim}
|
||||
|
|
@ -376,7 +376,7 @@ to create a gzipped tarball and a zip file. The available formats are:
|
|||
|
||||
|
||||
\subsection{The manifest and manifest template}
|
||||
\label{sec:manifest}
|
||||
\label{manifest}
|
||||
|
||||
Without any additional information, the \command{sdist} command puts a
|
||||
minimal set of files into the source distribution:
|
||||
|
|
@ -414,7 +414,7 @@ distribution root matching \code{*.txt}, all files anywhere under the
|
|||
\file{examples} directory matching \code{*.txt} or \code{*.py}, and
|
||||
exclude all directories matching \code{examples/sample?/build}. There
|
||||
are several other commands available in the manifest template
|
||||
mini-language; see section~\ref{sec:sdist-cmd}.
|
||||
mini-language; see section~\ref{sdist-cmd}.
|
||||
|
||||
The order of commands in the manifest template very much matters:
|
||||
initially, we have the list of default files as described above, and
|
||||
|
|
@ -454,7 +454,7 @@ That way, the manifest template is portable across operating systems.
|
|||
|
||||
|
||||
\subsection{Manifest-related options}
|
||||
\label{sec:manifest-options}
|
||||
\label{manifest-options}
|
||||
|
||||
The normal course of operations for the \command{sdist} command is as
|
||||
follows:
|
||||
|
|
@ -493,7 +493,7 @@ distribution will be empty.
|
|||
|
||||
|
||||
\section{Creating Built Distributions}
|
||||
\label{sec:built-dist}
|
||||
\label{built-dist}
|
||||
|
||||
A ``built distribution'' is what you're probably used to thinking of
|
||||
either as a ``binary package'' or an ``installer'' (depending on your
|
||||
|
|
@ -594,23 +594,23 @@ each, are:
|
|||
\end{tableii}
|
||||
|
||||
\section{Examples}
|
||||
\label{sec:examples}
|
||||
\label{examples}
|
||||
|
||||
|
||||
\subsection{Pure Python distribution (by module)}
|
||||
\label{sec:pure-mod}
|
||||
\label{pure-mod}
|
||||
|
||||
|
||||
\subsection{Pure Python distribution (by package)}
|
||||
\label{sec:pure-pkg}
|
||||
\label{pure-pkg}
|
||||
|
||||
|
||||
\subsection{Single extension module}
|
||||
\label{sec:single-ext}
|
||||
\label{single-ext}
|
||||
|
||||
|
||||
\subsection{Multiple extension modules}
|
||||
\label{sec:multiple-ext}
|
||||
\label{multiple-ext}
|
||||
|
||||
|
||||
\subsection{Putting it all together}
|
||||
|
|
@ -618,48 +618,48 @@ each, are:
|
|||
|
||||
|
||||
\section{Extending the Distutils}
|
||||
\label{sec:extending}
|
||||
\label{extending}
|
||||
|
||||
|
||||
\subsection{Extending existing commands}
|
||||
\label{sec:extend-existing}
|
||||
\label{extend-existing}
|
||||
|
||||
|
||||
\subsection{Writing new commands}
|
||||
\label{sec:new-commands}
|
||||
\label{new-commands}
|
||||
|
||||
|
||||
|
||||
\section{Reference}
|
||||
\label{sec:ref}
|
||||
\label{ref}
|
||||
|
||||
|
||||
\subsection{Building modules: the \protect\command{build} command family}
|
||||
\label{sec:build-cmds}
|
||||
\label{build-cmds}
|
||||
|
||||
\subsubsection{\protect\command{build}}
|
||||
\label{sec:build-cmd}
|
||||
\label{build-cmd}
|
||||
|
||||
\subsubsection{\protect\command{build\_py}}
|
||||
\label{sec:build-py-cmd}
|
||||
\label{build-py-cmd}
|
||||
|
||||
\subsubsection{\protect\command{build\_ext}}
|
||||
\label{sec:build-ext-cmd}
|
||||
\label{build-ext-cmd}
|
||||
|
||||
\subsubsection{\protect\command{build\_clib}}
|
||||
\label{sec:build-clib-cmd}
|
||||
\label{build-clib-cmd}
|
||||
|
||||
|
||||
\subsection{Installing modules: the \protect\command{install} command family}
|
||||
\label{sec:install-cmd}
|
||||
\label{install-cmd}
|
||||
|
||||
|
||||
\subsection{Cleaning up: the \protect\command{clean} command}
|
||||
\label{sec:clean-cmd}
|
||||
\label{clean-cmd}
|
||||
|
||||
|
||||
\subsection{Creating a source distribution: the \protect\command{sdist} command}
|
||||
\label{sec:sdist-cmd}
|
||||
\label{sdist-cmd}
|
||||
|
||||
|
||||
\XXX{fragment moved down from above: needs context!}
|
||||
|
|
@ -694,7 +694,7 @@ anything except backslash or colon; on Mac OS anything except colon.
|
|||
|
||||
\subsection{Creating a ``built'' distribution: the
|
||||
\protect\command{bdist} command family}
|
||||
\label{sec:bdist-cmds}
|
||||
\label{bdist-cmds}
|
||||
|
||||
|
||||
\subsubsection{\protect\command{blib}}
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@
|
|||
\tableofcontents
|
||||
|
||||
\section{Introduction}
|
||||
\label{sec:intro}
|
||||
\label{intro}
|
||||
|
||||
Although Python's extensive standard library covers many programming
|
||||
needs, there often comes a time when you need to add some new
|
||||
|
|
@ -66,7 +66,7 @@ the ``Distributing Python Modules'' manual.
|
|||
|
||||
|
||||
\subsection{Best case: trivial installation}
|
||||
\label{sec:trivial-inst}
|
||||
\label{trivial-inst}
|
||||
|
||||
In the best case, someone will have prepared a special version of the
|
||||
module distribution you want to install that is targeted specifically at
|
||||
|
|
@ -94,7 +94,7 @@ building and installing modules from standard source distributions.
|
|||
|
||||
|
||||
\subsection{The new standard: Distutils}
|
||||
\label{sec:new-standard}
|
||||
\label{new-standard}
|
||||
|
||||
If you download a module source distribution, you can tell pretty
|
||||
quickly if was packaged and distributed in the standard way, i.e. using
|
||||
|
|
@ -118,7 +118,7 @@ command is everything you need to get out of this manual.
|
|||
|
||||
|
||||
\subsection{The old way: no standards}
|
||||
\label{sec:old-way}
|
||||
\label{old-way}
|
||||
|
||||
Before the Distutils, there was no infrastructure to support installing
|
||||
third-party modules in a consistent, standardized way. Thus, it's not
|
||||
|
|
@ -147,13 +147,13 @@ developers---hence, we include documentation for builders/installers
|
|||
here.
|
||||
|
||||
All of the pre-Distutils material is tucked away in
|
||||
section~\ref{sec:pre-distutils}.
|
||||
section~\ref{pre-distutils}.
|
||||
|
||||
|
||||
\section{Standard Build and Install}
|
||||
\label{sec:normal-install}
|
||||
\label{normal-install}
|
||||
|
||||
As described in section~\ref{sec:new-standard}, building and installing
|
||||
As described in section~\ref{new-standard}, building and installing
|
||||
a module distribution using the Distutils is usually one simple command:
|
||||
\begin{verbatim}
|
||||
python setup.py install
|
||||
|
|
@ -227,7 +227,7 @@ python setup.py build --build-base=/tmp/pybuild/foo-1.0
|
|||
\end{verbatim}
|
||||
(Or you could do this permanently with a directive in your system or
|
||||
personal Distutils configuration file; see
|
||||
section~\ref{sec:config-files}.) Normally, this isn't necessary.
|
||||
section~\ref{config-files}.) Normally, this isn't necessary.
|
||||
|
||||
The default layout for the build tree is as follows:
|
||||
\begin{verbatim}
|
||||
|
|
@ -356,7 +356,7 @@ installations in the next section.
|
|||
\end{tableiii}}
|
||||
|
||||
\section{Alternate Installation}
|
||||
\label{sec:alt-install}
|
||||
\label{alt-install}
|
||||
|
||||
Often, it is necessary or desirable to install modules to a location
|
||||
other than the standard location for third-party Python modules. For
|
||||
|
|
@ -377,7 +377,7 @@ of the following section applies to you.
|
|||
|
||||
|
||||
\subsection{Alternate installation: Unix (the home scheme)}
|
||||
\label{sec:alt-unix-prefix}
|
||||
\label{alt-unix-prefix}
|
||||
|
||||
Under Unix, there are two ways to perform an alternate installation.
|
||||
The ``prefix scheme'' is similar to how alternate installation works
|
||||
|
|
@ -407,7 +407,7 @@ installation base as follows:
|
|||
{home}{/share}
|
||||
|
||||
\subsection{Alternate installation: Unix (the prefix scheme)}
|
||||
\label{sec:alt-unix-home}
|
||||
\label{alt-unix-home}
|
||||
|
||||
The ``prefix scheme'' is useful when you wish to use one Python
|
||||
installation to perform the build/install (i.e., to run the setup
|
||||
|
|
@ -479,7 +479,7 @@ point to an alternate Python installation, this is immaterial.)
|
|||
|
||||
|
||||
\subsection{Alternate installation: Windows}
|
||||
\label{sec:alt-windows}
|
||||
\label{alt-windows}
|
||||
|
||||
Since Windows has no conception of a user's home directory, and since
|
||||
the standard Python installation under Windows is simpler than that
|
||||
|
|
@ -502,7 +502,7 @@ Files are installed as follows:
|
|||
|
||||
|
||||
\subsection{Alternate installation: Mac~OS}
|
||||
\label{sec:alt-macos}
|
||||
\label{alt-macos}
|
||||
|
||||
Like Windows, Mac~OS has no notion of home directories (or even of
|
||||
users), and a fairly simple standard Python installation. Thus, only a
|
||||
|
|
@ -528,10 +528,10 @@ non-pure distributions''. Is this necessary?!?}
|
|||
|
||||
|
||||
\section{Custom Installation}
|
||||
\label{sec:custom-install}
|
||||
\label{custom-install}
|
||||
|
||||
Sometimes, the alternate installation schemes described in
|
||||
section~\ref{sec:alt-install} just don't do what you want. You might
|
||||
section~\ref{alt-install} just don't do what you want. You might
|
||||
want to tweak just one or two directories while keeping everything under
|
||||
the same base directory, or you might want to completely redefine the
|
||||
installation scheme. In either case, you're creating a \emph{custom
|
||||
|
|
@ -613,7 +613,7 @@ as it does when parsing your configuration file(s)).
|
|||
Obviously, specifying the entire installation scheme every time you
|
||||
install a new module distribution would be very tedious. Thus, you can
|
||||
put these options into your Distutils config file (see
|
||||
section~\ref{sec:config-files}):
|
||||
section~\ref{config-files}):
|
||||
\begin{verbatim}
|
||||
[install]
|
||||
install-base=$HOME
|
||||
|
|
@ -650,28 +650,28 @@ extra variables that may not be in your environment, such as
|
|||
\code{\$PLAT}. (And of course, you can only use the configuration
|
||||
variables supplied by the Distutils on systems that don't have
|
||||
environment variables, such as Mac~OS (\XXX{true?}).) See
|
||||
section~\ref{sec:config-files} for details.
|
||||
section~\ref{config-files} for details.
|
||||
|
||||
\XXX{need some Windows and Mac~OS examples---when would custom
|
||||
installation schemes be needed on those platforms?}
|
||||
|
||||
|
||||
\section{Distutils Configuration Files}
|
||||
\label{sec:config-files}
|
||||
\label{config-files}
|
||||
|
||||
\XXX{not even implemented yet, much less documented!}
|
||||
|
||||
|
||||
\section{Pre-Distutils Conventions}
|
||||
\label{sec:pre-distutils}
|
||||
\label{pre-distutils}
|
||||
|
||||
|
||||
\subsection{The Makefile.pre.in file}
|
||||
\label{sec:makefile-pre-in}
|
||||
\label{makefile-pre-in}
|
||||
|
||||
|
||||
\subsection{Installing modules manually}
|
||||
\label{sec:manual-install}
|
||||
\label{manual-install}
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue