Skip to content

Commit

Permalink
Merge pull request #219 from jim-easterbrook/devel
Browse files Browse the repository at this point in the history
Update installation documentation
  • Loading branch information
jim-easterbrook authored Oct 26, 2023
2 parents 9a8f54f + ee743d8 commit a9aa05b
Show file tree
Hide file tree
Showing 11 changed files with 716 additions and 160 deletions.
34 changes: 20 additions & 14 deletions src/doc/other/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Python_ is absolutely essential to run Photini.
It is already installed on many computers, but on Windows you will probably need to install it yourself.

.. tabs::
.. tab:: Linux/MacOS
.. group-tab:: Linux/MacOS

Python should already be installed, but make sure you have Python |nbsp| 3.
Open a terminal window and run the ``python3`` command::
Expand Down Expand Up @@ -59,7 +59,7 @@ It is already installed on many computers, but on Windows you will probably need
pip 23.1.2 from /home/jim/.local/lib/python3.8/site-packages/pip (python 3.8)


.. tab:: Windows
.. group-tab:: Windows

I suggest reading `Using Python on Windows`_ before you begin.
Go to https://www.python.org/downloads/windows/ and choose a suitable Python |nbsp| 3 installer.
Expand All @@ -69,13 +69,13 @@ It is already installed on many computers, but on Windows you will probably need
.. image:: ../images/screenshot_090.png

The first main installer screen should have an option to customise the installation.
I recommend choosing this and selection the following options.
I recommend choosing this and selecting the following options.

.. image:: ../images/screenshot_091.png

* Documentation: If you are installing Python only to run Photini then you don't really need the Python documentation.
* pip: You definitely need this!
* tcl/tk and IDLE: You don't need this unless you want to edit Python files.
* tcl/tk and IDLE: not needed unless you want to edit Python files.
* Python test suite: not needed.
* py launcher: I recommend installing the launcher for all users.

Expand Down Expand Up @@ -117,13 +117,16 @@ It is already installed on many computers, but on Windows you will probably need

If you install packages with ``pip`` as a normal user (i.e. without administrator privileges) it will put them under your "roaming" application data directory, e.g. ``c:\users\jim\appdata\roaming\python\python38\site-packages``.
I think this is a curious choice of location and strongly recommend using a "virtual environment" to install Photini and its dependencies in your choice of location.

The following instructions assume a virtual environment is in use and activated.
If you don't use a virtual environment then replace ``python`` with ``py`` and ``pip`` with ``py -m pip``.

Installing Photini
------------------

Before installing Photini you need to decide if you are installing it for a single user or for multiple users.
Multi-user installations use a Python `virtual environment`_ to create a self contained installation that can easily be shared.
Using a virtual environment has other advantages, such as easy uninstallation, so you could also use it for a single user installation.
Using a virtual environment has other advantages, such as easy uninstallation, so I recommend using it for a single user installation.

Linux & MacOS users have another decision to make - whether to install Photini's dependencies with pip_ or with the operating system's package manager.
For a good introduction to the advantages and disadvantages of each I suggest reading `Managing Python packages the right way`_.
Expand All @@ -133,10 +136,11 @@ Virtual environment
^^^^^^^^^^^^^^^^^^^

If you are using a virtual environment you should set it up now.
You can create a virtual environment in any writeable directory.
I use the name ``photini`` and create it in my home directory:

.. tabs::
.. tab:: Linux/MacOS
.. group-tab:: Linux/MacOS

::

Expand All @@ -152,10 +156,10 @@ I use the name ``photini`` and create it in my home directory:
Successfully uninstalled pip-20.0.2
Successfully installed pip-23.1.2

Note that pip may need to be updated again from within the virtual environment.
The option ``--system-site-packages`` makes packages installed with the system package manager (e.g. PySide6 / PySide2 / PyQt6 / PyQt5) available within the virtual environment.
Note that pip may need to be updated again from within the virtual environment.

.. tab:: Windows
.. group-tab:: Windows

::

Expand All @@ -175,7 +179,7 @@ I use the name ``photini`` and create it in my home directory:
Successfully uninstalled pip-21.1.1
Successfully installed pip-23.3.1

Note that after activating the virtual environment the ``py`` command is not used.
Note that after activating the virtual environment the ``py`` command is not needed.
Python, pip, and other Python based commands are run directly.
After creating the virtual environment you should update ``pip`` as shown above.
This ensures that the latest version will be used to install Photini.
Expand Down Expand Up @@ -754,7 +758,8 @@ Otherwise you can use pip to uninstall Photini and as many of its dependencies a
Updating Photini
----------------

When a new release of Photini is issued you can easily update your installation with pip_:
When a new release of Photini is issued you can easily update your installation with pip_.
If you installed Photini in a virtual environment then you need to activate the virtual environment before upgrading:

.. tabs::
.. code-tab:: none Linux/MacOS
Expand Down Expand Up @@ -887,6 +892,7 @@ If you installed Photini in a `virtual environment`_ then activate that environm
.. code-tab:: none Windows

C:\Users\Jim>c:\Users\Jim\photini\Scripts\activate.bat

(photini) C:\Users\Jim>

Start the Photini program as follows.
Expand All @@ -898,7 +904,7 @@ If it fails to run you should get some diagnostic information:
jim@brains:~$ python3 -m photini -v
.. code-tab:: none Windows

C:\Users\Jim>python -m photini -v
(photini) C:\Users\Jim>python -m photini -v

Note the use of the ``-v`` option to increase the verbosity of Photini's message logging.
This option can be repeated for even more verbosity.
Expand All @@ -921,12 +927,12 @@ To find out what version of Photini and some of its dependencies you are using,
using style: qt5ct-style
.. code-tab:: none Windows

C:\Users\Jim>python -m photini --version
(photini) C:\Users\Jim>python -m photini --version
ffmpeg or ffprobe not found
Photini 2023.7.0, build release
Photini 2023.10.0, build release
Python 3.8.10 (tags/v3.8.10:3d8993a, May 3 2021, 11:48:03) [MSC v.1928 64 bit (AMD64)]
python-exiv2 0.14.1, exiv2 0.27.7
PyQt 5.15.9, Qt 5.15.2, locale en-GB
PyQt 5.15.10, Qt 5.15.2, locale en-GB
PyEnchant 3.2.2
available styles: windowsvista, Windows, Fusion
using style: windowsvista
Expand Down
95 changes: 80 additions & 15 deletions src/lang/ca/LC_MESSAGES/documentation.po
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ msgid ""
msgstr ""
"Project-Id-Version: Photini 2023.4.1\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2023-10-25 15:44+0100\n"
"POT-Creation-Date: 2023-10-26 11:01+0100\n"
"PO-Revision-Date: 2023-04-19 08:54+0000\n"
"Last-Translator: Joan <[email protected]>, 2023\n"
"Language: ca\n"
Expand Down Expand Up @@ -2486,7 +2486,7 @@ msgstr ""

msgid ""
"The first main installer screen should have an option to customise the "
"installation. I recommend choosing this and selection the following options."
"installation. I recommend choosing this and selecting the following options."
msgstr ""

msgid ""
Expand All @@ -2497,7 +2497,7 @@ msgstr ""
msgid "pip: You definitely need this!"
msgstr ""

msgid "tcl/tk and IDLE: You don't need this unless you want to edit Python files."
msgid "tcl/tk and IDLE: not needed unless you want to edit Python files."
msgstr ""

msgid "Python test suite: not needed."
Expand Down Expand Up @@ -2562,6 +2562,12 @@ msgid ""
"choice of location."
msgstr ""

msgid ""
"The following instructions assume a virtual environment is in use and "
"activated. If you don't use a virtual environment then replace ``python`` "
"with ``py`` and ``pip`` with ``py -m pip``."
msgstr ""

msgid "Installing Photini"
msgstr ""

Expand All @@ -2570,8 +2576,7 @@ msgid ""
"single user or for multiple users. Multi-user installations use a Python "
"`virtual environment`_ to create a self contained installation that can "
"easily be shared. Using a virtual environment has other advantages, such as "
"easy uninstallation, so you could also use it for a single user "
"installation."
"easy uninstallation, so I recommend using it for a single user installation."
msgstr ""

msgid ""
Expand All @@ -2590,22 +2595,23 @@ msgid "Virtual environment"
msgstr ""

msgid ""
"If you are using a virtual environment you should set it up now. I use the "
"name ``photini`` and create it in my home directory:"
"If you are using a virtual environment you should set it up now. You can "
"create a virtual environment in any writeable directory. I use the name "
"``photini`` and create it in my home directory:"
msgstr ""

msgid ""
"Note that pip may need to be updated again from within the virtual "
"environment. The option ``--system-site-packages`` makes packages installed "
"with the system package manager (e.g. PySide6 / PySide2 / PyQt6 / PyQt5) "
"available within the virtual environment."
"The option ``--system-site-packages`` makes packages installed with the "
"system package manager (e.g. PySide6 / PySide2 / PyQt6 / PyQt5) available "
"within the virtual environment. Note that pip may need to be updated again "
"from within the virtual environment."
msgstr ""

msgid ""
"Note that after activating the virtual environment the ``py`` command is not"
" used. Python, pip, and other Python based commands are run directly. After "
"creating the virtual environment you should update ``pip`` as shown above. "
"This ensures that the latest version will be used to install Photini."
" needed. Python, pip, and other Python based commands are run directly. "
"After creating the virtual environment you should update ``pip`` as shown "
"above. This ensures that the latest version will be used to install Photini."
msgstr ""

msgid ""
Expand Down Expand Up @@ -2757,7 +2763,8 @@ msgstr ""

msgid ""
"When a new release of Photini is issued you can easily update your "
"installation with pip_:"
"installation with pip_. If you installed Photini in a virtual environment "
"then you need to activate the virtual environment before upgrading:"
msgstr ""

msgid ""
Expand Down Expand Up @@ -4140,3 +4147,61 @@ msgstr ""
#~ msgid "Spanish translation by Esteban Martinena, Cristos Ruiz"
#~ msgstr ""

#~ msgid ""
#~ "The first main installer screen should "
#~ "have an option to customise the "
#~ "installation. I recommend choosing this and"
#~ " selection the following options."
#~ msgstr ""

#~ msgid "tcl/tk and IDLE: You don't need this unless you want to edit Python files."
#~ msgstr ""

#~ msgid ""
#~ "Before installing Photini you need to "
#~ "decide if you are installing it for"
#~ " a single user or for multiple "
#~ "users. Multi-user installations use a "
#~ "Python `virtual environment`_ to create a"
#~ " self contained installation that can "
#~ "easily be shared. Using a virtual "
#~ "environment has other advantages, such as"
#~ " easy uninstallation, so you could also"
#~ " use it for a single user "
#~ "installation."
#~ msgstr ""

#~ msgid ""
#~ "If you are using a virtual "
#~ "environment you should set it up now."
#~ " I use the name ``photini`` and "
#~ "create it in my home directory:"
#~ msgstr ""

#~ msgid ""
#~ "Note that pip may need to be "
#~ "updated again from within the virtual "
#~ "environment. The option ``--system-site-"
#~ "packages`` makes packages installed with "
#~ "the system package manager (e.g. PySide6"
#~ " / PySide2 / PyQt6 / PyQt5) "
#~ "available within the virtual environment."
#~ msgstr ""

#~ msgid ""
#~ "Note that after activating the virtual "
#~ "environment the ``py`` command is not "
#~ "used. Python, pip, and other Python "
#~ "based commands are run directly. After "
#~ "creating the virtual environment you should"
#~ " update ``pip`` as shown above. This "
#~ "ensures that the latest version will "
#~ "be used to install Photini."
#~ msgstr ""

#~ msgid ""
#~ "When a new release of Photini is "
#~ "issued you can easily update your "
#~ "installation with pip_:"
#~ msgstr ""

Loading

0 comments on commit a9aa05b

Please sign in to comment.