Merge lp:~mitya57/ubuntu-packaging-guide/goodbye-python-packaging-page into lp:ubuntu-packaging-guide

[Dmitry Shachnev]

Remove Python Packaging page in favour of a link to Debian wiki.

That page was written in 2012, and since then many things happened in
Python world, like PyBuild and deprecation of Python 2.

The Debian wiki is kept up-to-date, while we are not in sync.

This also updates information about running Lintian (and mentions Lintian4Python where needed).

[Daniel Holbach (dholbach)]

Thanks. Good work!

review: Approve

=== modified file 'debian/changelog'
--- debian/changelog	2014-05-05 10:24:17 +0000
+++ debian/changelog	2014-05-05 13:30:54 +0000
@@ -3,6 +3,10 @@
   [ Dmitry Shachnev ]
   * Fix a typo and regenerate the .pot file (LP: #1309861).
   * Use anonymous links where possible to make translation easier.
+  * Add more information about Lintian.
+  * Remove Python Packaging page in favour of a link from index page
+    to Debian wiki. Our guide is terribly outdated, while Debian’s one
+    is kept up-to-date.
 
   [ Daniel Holbach ]
   * Changed "phone and table" to "phone and tablet".

=== modified file 'ubuntu-packaging-guide/index.rst'
--- ubuntu-packaging-guide/index.rst	2014-05-03 17:19:42 +0000
+++ ubuntu-packaging-guide/index.rst	2014-05-05 13:30:54 +0000
@@ -85,7 +85,6 @@
    udd-merging
    chroots
    traditional-packaging
-   python-packaging
    kde
 
 Further Reading
@@ -100,7 +99,8 @@
 * `How to package for Debian <HowToPackage_>`_;
 * `Debian Policy Manual <Policy_>`_;
 * `Debian New Maintainers' Guide <NewMaintGuide_>`_ — available in many languages;
-* `Packaging tutorial <PkgTutorial_>`_ (also available as a `package <PkgTutorialPkg_>`_).
+* `Packaging tutorial <PkgTutorial_>`_ (also available as a `package <PkgTutorialPkg_>`_);
+* `Guide for Packaging Python Modules <PythonModules_>`_.
 
 We are always looking to improve this guide. If you find any problems or have
 some suggestions, please `report a bug on Launchpad <Bugs_>`_.
@@ -114,3 +114,4 @@
 .. _PkgTutorialPkg: https://launchpad.net/ubuntu/+source/packaging-tutorial
 .. _Bugs: https://bugs.launchpad.net/ubuntu-packaging-guide
 .. _Source: https://code.launchpad.net/~ubuntu-packaging-guide-team/ubuntu-packaging-guide/trunk
+.. _PythonModules: https://wiki.debian.org/Python/LibraryStyleGuide

=== modified file 'ubuntu-packaging-guide/packaging-new-software.rst'
--- ubuntu-packaging-guide/packaging-new-software.rst	2014-05-03 17:19:42 +0000
+++ ubuntu-packaging-guide/packaging-new-software.rst	2014-05-05 13:30:54 +0000
@@ -156,14 +156,20 @@
 
 Even if it builds the .deb binary package, your packaging may have
 bugs.  Many errors can be automatically detected by our tool
-``lintian`` which can be run on both the source .dsc metadata file and
-the .deb binary package::
+``lintian`` which can be run on the source .dsc metadata file, .deb
+binary packages or .changes file::
 
     $ lintian hello_2.7-0ubuntu1.dsc
     $ lintian hello_2.7-0ubuntu1_amd64.deb
 
-A description of each of the problems it reports can be found on the
-`lintian website <Lintian_>`_.
+To see verbose description of the problems use ``--info`` lintian flag
+or ``lintian-info`` command.
+
+Results of Ubuntu archive checks can be found online on
+http://lintian.ubuntuwire.org.
+
+For Python packages, there is also a ``lintian4python`` tool that provides
+some additional lintian checks.
 
 After making a fix to the packaging you can rebuild using ``-nc`` "no clean"
 without having to build from scratch::
@@ -237,7 +243,6 @@
 .. _PPA: https://help.launchpad.net/Packaging/PPA
 .. _GNU.org: http://www.gnu.org/software/hello/
 .. _`packages.ubuntu.com`:  http://packages.ubuntu.com/
-.. _Lintian: http://lintian.debian.org/tags.html
 .. _ubuntu-motu: https://lists.ubuntu.com/mailman/listinfo/ubuntu-motu
 .. _MentorsFAQ: https://wiki.debian.org/DebianMentorsFaq
 .. _WNPP: http://www.debian.org/devel/wnpp/

=== removed file 'ubuntu-packaging-guide/python-packaging.rst'
--- ubuntu-packaging-guide/python-packaging.rst	2012-10-16 12:17:54 +0000
+++ ubuntu-packaging-guide/python-packaging.rst	1970-01-01 00:00:00 +0000
@@ -1,142 +0,0 @@
-=========================================
-Packaging Python modules and applications
-=========================================
-
-Our packaging follows Debian’s `Python policy`_. We will use the `python-markdown`_ package as an example, which can be downloaded from `PyPI`_. You can look at its packaging at its `Subversion repository`_.
-
-There are two types of Python packages — *modules* and *apps*.
-
-At the time of writing, Ubuntu has two incompatible versions of Python — *2.x* and *3.x*. ``/usr/bin/python`` is a symbolic link to a default Python 2.x version, and ``/usr/bin/python3`` — to a default Python 3.x version. Python modules should be built against all supported Python versions.
-
-If you are going to package a new Python module, you might find the ``py2dsc`` tool useful (available in `python-stdeb`_ package).
-
-debian/control
---------------
-
-Python 2.x and 3.x versions of the package should be in separate binary packages. Names should have ``python{,3}-modulename`` format (like: ``python3-dbus.mainloop.qt``). Here, we will use ``python-markdown`` and ``python3-markdown`` for module packages and ``python-markdown-doc`` for the documentation package.
-
-Things in ``debian/control`` that are specific for a Python package:
-
-- The section of module packages should be ``python``, and ``doc`` for the documentation package. For an application, a single binary package will be enough.
-- We should add build dependencies on ``python-all (>= 2.6.6-3~)`` and ``python3-all (>= 3.1.2-7~)`` to make sure Python helpers are available (see the next section for details).
-- It’s recommended to add ``X-Python-Version`` and ``X-Python3-Version`` fields — see “`Specifying Supported Versions`_” section of the Policy for details. For example::
-  
-    X-Python-Version: >= 2.6
-    X-Python3-Version: >= 3.1
-  
-  If your package works only with Python 2.x or 3.x, build depend only on one ``-all`` package and use only one ``-Version`` field.
-- Module packages should have ``{python:Depends}`` and ``{python3:Depends}`` substitution variables (respectively) in their dependency lists.
-
-debian/rules
-------------
-
-The recommended helpers for python modules are ``dh_python2`` and ``dh_python3``. Unfortunately, ``debhelper`` doesn’t yet build Python 3.x packages automatically (see `bug 597105`_ in Debian BTS), so we’ll need to do that manually in override sections (skip this if your package doesn’t support Python 3.x).
-
-Here’s our ``debian/rules`` file (with annotations):
-
-.. code-block:: makefile
-
-   # These commands build the list of supported Python 3 versions
-   # The last version should be just “python3” so that the scripts
-   # get a correct shebang.
-   # Use just “PYTHON3 := $(shell py3versions -r)” if your package
-   # doesn’t contain scripts
-   PY3REQUESTED := $(shell py3versions -r)
-   PY3DEFAULT := $(shell py3versions -d)
-   PYTHON3 := $(filter-out $(PY3DEFAULT),$(PY3REQUESTED)) python3
-   
-   %:
-       # Adding the required helpers
-       dh $@ --with python2,python3
-
-   override_dh_auto_clean:
-       dh_auto_clean
-       rm -rf build/
-   
-   override_dh_auto_build:
-       # Build for each Python 3 version
-       set -ex; for python in $(PYTHON3); do \
-           $$python setup.py build; \
-       done
-       dh_auto_build
-   
-   override_dh_auto_install:
-       # The same for install; note the --install-layout=deb option
-       set -ex; for python in $(PYTHON3); do \
-           $$python setup.py install --install-layout=deb --root=debian/tmp; \
-       done
-       dh_auto_install
-
-It is also a good practice to run tests during the build, if they are shipped by upstream. Usually tests can be invoked using ``setup.py test`` or ``setup.py check``.
-
-debian/\*.install
------------------
-
-Python 2.x modules are installed into ``/usr/share/pyshared/`` directory, and symbolic links are created in ``/usr/lib/python2.x/dist-packages/`` for every interpreter version, while Python 3.x ones are all installed into ``/usr/lib/python3/dist-packages/``.
-
-If your package is an application and has private Python modules, they should be installed in ``/usr/share/module``, or ``/usr/lib/module`` if the modules are architecture-dependent (e.g. extensions) (see “`Programs Shipping Private Modules`_” section of the Policy).
-
-So, our ``python-markdown.install`` file will look like this (we’ll also want to install a ``markdown_py`` executable)::
-
-  usr/lib/python2.*/
-  usr/bin/
-
-and ``python3-markdown.install`` will only have one line::
-
-  usr/lib/python3/
-
-The ``-doc`` package
---------------------
-
-The tool most commonly used for building Python docs is `Sphinx`_. To add Sphinx documentation to your package (using ``dh_sphinxdoc`` helper), you should:
-
-* Add a build-dependency on ``python-sphinx`` or ``python3-sphinx`` (depending on what Python version do you want to use);
-* Append ``sphinxdoc`` to the ``dh --with`` line;
-* Run ``setup.py build_sphinx`` in ``override_dh_auto_build`` (sometimes not needed);
-* Add ``{sphinxdoc:Depends}`` to the dependency list of your ``-doc`` package;
-* Add the path of the built docs directory (usually ``build/sphinx/html``) to your ``.docs`` file.
-
-In our case, the docs are automatically built in ``build/docs/`` directory when we run ``setup.py build``, so we can simply put this in the ``python-markdown-doc.docs`` file::
-
-  build/docs/
-
-Because docs also contain source ``.txt`` files, we’ll also tell ``dh_compress`` to not compress them — by adding this to ``debian/rules``:
-
-.. code-block:: makefile
-
-   override_dh_compress:
-       dh_compress -X.txt
-
-Checking for packaging mistakes
--------------------------------
-
-Along with ``lintian``, there is a special tool for checking Python packages — ``lintian4py``. It is available in the `lintian4python`_ package. For example, these two commands invoke both versions of ``lintian`` and check source and binary packages::
-
-  lintian -EI --pedantic *.dsc *.deb
-  lintian4py -EI --pedantic *.dsc *.deb
-
-Here, ``-EI`` option is used to enable experimental and informational tags.
-
-See also
---------
-
-* The `Python policy`_;
-* `Python/Packaging`_ article on Debian wiki;
-* `Python/LibraryStyleGuide`_ and `Python/AppStyleGuide`_ articles on Debian wiki;
-* Debian `python-modules`_ and `python-apps`_ teams.
-
-.. _`Python policy`: http://www.debian.org/doc/packaging-manuals/python-policy/
-.. _`python-markdown`: http://packages.python.org/Markdown/
-.. _`PyPI`: http://pypi.python.org/pypi/Markdown/
-.. _`Subversion repository`: http://anonscm.debian.org/viewvc/python-modules/packages/python-markdown/trunk/debian/
-.. _`python-stdeb`: https://launchpad.net/ubuntu/+source/stdeb
-.. _`bug 597105`: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=597105
-.. _`Specifying Supported Versions`: http://www.debian.org/doc/packaging-manuals/python-policy/ch-module_packages.html#s-specifying_versions
-.. _`Programs Shipping Private Modules`: http://www.debian.org/doc/packaging-manuals/python-policy/ch-programs.html#s-current_version_progs
-.. _`Sphinx`: http://sphinx.pocoo.org/
-.. _`lintian4python`: https://launchpad.net/ubuntu/+source/lintian4python
-.. _`Python/Packaging`: http://wiki.debian.org/Python/Packaging
-.. _`Python/LibraryStyleGuide`: http://wiki.debian.org/Python/LibraryStyleGuide
-.. _`Python/AppStyleGuide`: http://wiki.debian.org/Python/AppStyleGuide
-.. _`python-modules`: http://wiki.debian.org/Teams/PythonModulesTeam/
-.. _`python-apps`: http://wiki.debian.org/Teams/PythonAppsPackagingTeam/