From 73e379cc55ac1e9ec63c4ac30b75ecc82418f513 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Wed, 23 Sep 2020 20:29:14 -0400 Subject: Use canonical extension for docs. --- docs/userguide/development_mode.rst | 60 +++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 docs/userguide/development_mode.rst (limited to 'docs/userguide/development_mode.rst') diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst new file mode 100644 index 00000000..9d4e7581 --- /dev/null +++ b/docs/userguide/development_mode.rst @@ -0,0 +1,60 @@ +"Development Mode" +================== + +Under normal circumstances, the ``distutils`` assume that you are going to +build a distribution of your project, not use it in its "raw" or "unbuilt" +form. If you were to use the ``distutils`` that way, you would have to rebuild +and reinstall your project every time you made a change to it during +development. + +Another problem that sometimes comes up with the ``distutils`` is that you may +need to do development on two related projects at the same time. You may need +to put both projects' packages in the same directory to run them, but need to +keep them separate for revision control purposes. How can you do this? + +Setuptools allows you to deploy your projects for use in a common directory or +staging area, but without copying any files. Thus, you can edit each project's +code in its checkout directory, and only need to run build commands when you +change a project's C extensions or similarly compiled files. You can even +deploy a project into another project's checkout directory, if that's your +preferred way of working (as opposed to using a common independent staging area +or the site-packages directory). + +To do this, use the ``setup.py develop`` command. It works very similarly to +``setup.py install``, except that it doesn't actually install anything. +Instead, it creates a special ``.egg-link`` file in the deployment directory, +that links to your project's source code. And, if your deployment directory is +Python's ``site-packages`` directory, it will also update the +``easy-install.pth`` file to include your project's source code, thereby making +it available on ``sys.path`` for all programs using that Python installation. + +If you have enabled the ``use_2to3`` flag, then of course the ``.egg-link`` +will not link directly to your source code when run under Python 3, since +that source code would be made for Python 2 and not work under Python 3. +Instead the ``setup.py develop`` will build Python 3 code under the ``build`` +directory, and link there. This means that after doing code changes you will +have to run ``setup.py build`` before these changes are picked up by your +Python 3 installation. + +In addition, the ``develop`` command creates wrapper scripts in the target +script directory that will run your in-development scripts after ensuring that +all your ``install_requires`` packages are available on ``sys.path``. + +You can deploy the same project to multiple staging areas, e.g. if you have +multiple projects on the same machine that are sharing the same project you're +doing development work. + +When you're done with a given development task, you can remove the project +source from a staging area using ``setup.py develop --uninstall``, specifying +the desired staging area if it's not the default. + +There are several options to control the precise behavior of the ``develop`` +command; see the section on the `develop`_ command below for more details. + +Note that you can also apply setuptools commands to non-setuptools projects, +using commands like this:: + + python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop + +That is, you can simply list the normal setup commands and options following +the quoted part. \ No newline at end of file -- cgit v1.2.1 From edfa441febf6c5d8af8973ce952b3a0c19b7b575 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Fri, 16 Oct 2020 01:14:51 +0200 Subject: =?UTF-8?q?=F0=9F=93=9D=20Recover=20interdoc=20links=20&=20correct?= =?UTF-8?q?=20broken=20syntax?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/userguide/development_mode.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/userguide/development_mode.rst') diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst index 9d4e7581..bce724a7 100644 --- a/docs/userguide/development_mode.rst +++ b/docs/userguide/development_mode.rst @@ -49,7 +49,7 @@ source from a staging area using ``setup.py develop --uninstall``, specifying the desired staging area if it's not the default. There are several options to control the precise behavior of the ``develop`` -command; see the section on the `develop`_ command below for more details. +command; see the section on the :ref:`develop ` command below for more details. Note that you can also apply setuptools commands to non-setuptools projects, using commands like this:: @@ -57,4 +57,4 @@ using commands like this:: python -c "import setuptools; with open('setup.py') as f: exec(compile(f.read(), 'setup.py', 'exec'))" develop That is, you can simply list the normal setup commands and options following -the quoted part. \ No newline at end of file +the quoted part. -- cgit v1.2.1 From 13d7bcb994097895ed7f6c6af419e3a037fe90a7 Mon Sep 17 00:00:00 2001 From: Daniel Moore Date: Wed, 23 Dec 2020 14:39:27 -0800 Subject: Clarify Development Mode first paragraph --- docs/userguide/development_mode.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/userguide/development_mode.rst') diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst index bce724a7..3c477ec1 100644 --- a/docs/userguide/development_mode.rst +++ b/docs/userguide/development_mode.rst @@ -3,9 +3,9 @@ Under normal circumstances, the ``distutils`` assume that you are going to build a distribution of your project, not use it in its "raw" or "unbuilt" -form. If you were to use the ``distutils`` that way, you would have to rebuild -and reinstall your project every time you made a change to it during -development. +form. However, if you were to use the ``distutils`` to build a distribution, +you would have to rebuild and reinstall your project every time you made a +change to it during development. Another problem that sometimes comes up with the ``distutils`` is that you may need to do development on two related projects at the same time. You may need -- cgit v1.2.1 From ca296ca8663a376f3c36c9f8fd86b10ba81366c2 Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Sun, 18 Jul 2021 09:27:21 +0100 Subject: remove lib2to3 usage --- docs/userguide/development_mode.rst | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/userguide/development_mode.rst') diff --git a/docs/userguide/development_mode.rst b/docs/userguide/development_mode.rst index 3c477ec1..90bc5676 100644 --- a/docs/userguide/development_mode.rst +++ b/docs/userguide/development_mode.rst @@ -28,14 +28,6 @@ Python's ``site-packages`` directory, it will also update the ``easy-install.pth`` file to include your project's source code, thereby making it available on ``sys.path`` for all programs using that Python installation. -If you have enabled the ``use_2to3`` flag, then of course the ``.egg-link`` -will not link directly to your source code when run under Python 3, since -that source code would be made for Python 2 and not work under Python 3. -Instead the ``setup.py develop`` will build Python 3 code under the ``build`` -directory, and link there. This means that after doing code changes you will -have to run ``setup.py build`` before these changes are picked up by your -Python 3 installation. - In addition, the ``develop`` command creates wrapper scripts in the target script directory that will run your in-development scripts after ensuring that all your ``install_requires`` packages are available on ``sys.path``. -- cgit v1.2.1