diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 41c2344..aaf4cc9 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -202,7 +202,7 @@ To create a standalone windowed OS X application, use the :code:`--windowed` opt This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use GUI packages in your Python code, like `PyQt `_ or `PySide `_, to control the graphical parts of the app. -There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option. +There are several options in :code:`script.spec` related to Mac OS X app bundles `here `_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option. Linux diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 24eb274..bd7733b 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -77,6 +77,15 @@ or Python 3: This will take a minute or two. +Homebrew names the executable ``python2`` so that you can still run the system Python via the executable ``python``. + + +.. code-block:: console + + $ python -V # system Python interpreter + $ python2 -V # Homebrew installed Python 2 interpreter + $ python3 -V # Homebrew installed Python 3 interpreter (if installed) + Setuptools & Pip ---------------- @@ -93,6 +102,12 @@ that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_, and is actively maintained. +.. code-block:: console + + $ pip2 -V # pip pointing to the Homebrew installed Python 2 interpreter + $ pip3 -V # pip pointing to the Homebrew installed Python 3 interpreter (if installed) + + Virtual Environments -------------------- diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst index 8844f2e..14adc77 100644 --- a/docs/starting/install3/osx.rst +++ b/docs/starting/install3/osx.rst @@ -70,8 +70,7 @@ Pip Homebrew installs ``pip3`` for you. -``pip3`` is the alias for the Python 3 version of ``pip`` on systems with both -the Homebrew'd Python 2 and 3 installed. +``pip3`` is the alias to ``pip`` pointing to the Homebrew'd Python 3. Working with Python 3 --------------------- @@ -84,18 +83,22 @@ version of Python 3 as well. $ python -will launch the Python 2 interpreter. +will launch the system Python interpreter. + +.. code-block:: console + + $ python2 + +will launch the homebrew-installed Python 2 interpreter (if any). .. code-block:: console $ python3 -will launch the Python 3 interpreter. +will launch the homebrew-installed Python 3 interpreter. -``pip3`` and ``pip`` will both be available. If the Homebrew version of Python -2 is not installed, they will be the same. If the Homebrew version of Python 2 -is installed then ``pip`` will point to Python 2 and ``pip3`` will point to -Python 3. +If the Homebrew version of Python 2 is installed then ``pip2`` will point to Python 2. +If the Homebrew version of Python 3 is installed then ``pip3`` will point to Python 3. Virtual Environments diff --git a/docs/starting/install3/win.rst b/docs/starting/install3/win.rst index 6010b0b..bb6c38f 100644 --- a/docs/starting/install3/win.rst +++ b/docs/starting/install3/win.rst @@ -1,7 +1,7 @@ .. _install3-windows: Installing Python 3 on Windows -============================ +============================== First, download the `latest version `_ of Python 3.6 from the official website. If you want to be sure you are installing a fully diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index bdd39e1..a91b86b 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -205,8 +205,8 @@ more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters. For more detailed documentation of code a popular style is the one used for the -Numpy project, often called `Numpy style`_ docstrings. While it can take up a -few more lines the previous example, it allows the developer to include a lot +Numpy project, often called `Numpy style`_ docstrings. While it can take up more +lines than the previous example, it allows the developer to include a lot more information about a method, function, or class. :: def random_number_generator(arg1, arg2): diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index fcf1439..4a28085 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -230,13 +230,27 @@ Here's nice trick for removing all of these files, if they already exist:: Run that from the root directory of your project, and all ``.pyc`` files will suddenly vanish. Much better. +Version Control Ignores +~~~~~~~~~~~~~~~~~~~~~~~ +If you still need the ``.pyc`` files for performance reasons, you can always add them +to the ignore files of your version control repositories. Popular version control +systems have the ability to use wildcards defined in a file to apply special +rules. +An ignore file will make sure the matching files don't get checked into the repository. +Git_ uses ``.gitignore`` while Mercurial_ uses ``.hgignore``. +.. _Git: https://git-scm.com/ +.. _Mercurial: https://www.mercurial-scm.org/ +At the minimum your ignore files should look like this. +:: + syntax:glob # This line is not needed for .gitignore files. + *.py[cod] # Will match .pyc, .pyo and .pyd files. + __pycache__/ # Exclude the whole folder - - - +You may wish to include more files and directories depending on your needs. +The next time you commit to the repository, these files will not be included. diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index b33d6f6..486004c 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -391,7 +391,17 @@ folder named :file:`my` which is not the case. There is an dot notation should be used in the Python docs. If you'd like you could name your module :file:`my_spam.py`, but even our -friend the underscore should not be seen often in module names. +friend the underscore should not be seen often in module names. However, using other +characters (spaces or hyphens) in module names will prevent importing +(- is the subtract operator), so try to keep module names short so there is +no need to separate words. And, most of all, don't namespace with underscores, use submodules instead. + +.. code-block:: python + + # OK + import library.plugin.foo + # not OK + import library.foo_plugin Aside from some naming restrictions, nothing special is required for a Python file to be a module, but you need to understand the import mechanism in order