From 8488a8528825566fe25566df7f48b94870de1cce Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Sun, 12 Feb 2023 21:46:15 +0100 Subject: [PATCH 1/4] Update docs info on debian install --- .github/workflows/build.yml | 1 - docs/source/int_started.rst | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ba52ed3c..88b16ebc 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -73,4 +73,3 @@ jobs: name: novelWriter-${{ env.VERSION }}-macos.dmg path: dist_macos/novelWriter-${{ env.VERSION }}.dmg retention-days: 1 - diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index 42002efc..3890d75f 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -83,7 +83,7 @@ Instead, run the following commands to add the repository and key: .. code-block:: bash sudo gpg --no-default-keyring --keyring /usr/share/keyrings/novelwriter-ppa-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F19F1FCE50043114 - echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/novelwriter.list + echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu jammy main" | sudo tee /etc/apt/sources.list.d/novelwriter.list Then run the update and install commands as for Ubuntu: @@ -94,8 +94,8 @@ Then run the update and install commands as for Ubuntu: .. note:: - Please use the Ubuntu 20.04 (focal) packages for Debian. The newer Ubuntu packages use a - different compression algorithm that Debian doesn't currently support. + You may need to use the Ubuntu 20.04 (focal) packages for Debian 11 or earlier. The newer Ubuntu + packages use a different compression algorithm that may not be supported. AppImage Releases From 902dcc6ba774e089be8eb6e04fd21b53cc66e5f8 Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Mon, 13 Feb 2023 08:34:17 +0100 Subject: [PATCH 2/4] Update MacOS install instructions formatting --- docs/source/int_started.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index 7274e53b..c8289e65 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -111,18 +111,20 @@ They can of course be run on any Linux distro, if you prefer this to native pack Install on MacOS ================ -You can install novelWriter with both its Python and library dependencies embedded using the -DMG application image file from the `main website`_, or from the Releases_ page on GitHub. -Installing it should be straightforward. +You can install novelWriter with both its Python and library dependencies embedded using the DMG +application image file from the `main website`_, or from the Releases_ page on GitHub. Installing +it should be straightforward. -Download the DMG file and open it. Then drag the novelWriter icon to the Applications folder on -the right. This will install it into your Applications. The first time you try to launch it, it will -say that the bundle cannot be verified, simply press the “open” button to add an exception. -If you are not presented with an "open" button in the dialog launch the application again by -right clicking on the application in Finder and selecting "Open" from the context menu. +* Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications` + folder on the right. This will install it into your :guilabel:`Applications`. +* The first time you try to launch it, it will say that the bundle cannot be verified, simply press + the :guilabel:`Open` button to add an exception. +* If you are not presented with an :guilabel:`Open` button in the dialog launch the application + again by right clicking on the application in Finder and selecting :guilabel:`Open` from the + context menu. -The context menu can also be accessed by option clicking if you have a one button mouse. -This is done by holding down the option key on your keyboard and clicking on the application in Finder. +The context menu can also be accessed by option-clicking if you have a one button mouse. This is +done by holding down the option key on your keyboard and clicking on the application in Finder. .. _a_started_minimal: From ed892f3f155e75a641c9a0871f363328a6a280d9 Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Mon, 13 Feb 2023 08:38:19 +0100 Subject: [PATCH 3/4] Move the section on setting up Python on Windows to the PyPi part --- docs/source/int_started.rst | 60 ++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index c8289e65..c95e3827 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -141,31 +141,6 @@ These zip files don't include any dependencies, so you must install them separat .. _a_started_minimal_windows: -Minimal Package on Windows --------------------------- - -First, make sure you have Python installed on your system. If you don't, you can download it from -`python.org`_. Python 3.7 or higher is required, but it is recommended that you install the latest -version. - -Make sure you select the "Add Python to PATH" option during installation, otherwise the ``python`` -command will not work in the command line window. - -.. figure:: images/python_win_install.png - :align: center - :width: 500 - -When Python is installed, extract the novelWriter zip file and move the extracted folder to a -suitable location. You should probably not keep it on your desktop or in your downloads folder -where it may be accidentally deleted. Instead, move and rename it to for instance -``C:\novelWriter``. - -After you've got the folder where you want it, open it and double-click the file named -``windows_install.bat``. This will open a command line window and run the setup script to install -dependencies, and add desktop and start menu icons. - -Running ``windows_uninstall.bat`` will reverse the process if you wish to uninstall. After that, -you can just delete the novelWriter folder. .. _a_started_minimal_linux: @@ -243,8 +218,8 @@ novelWriter is also available on the Python Package Index, or PyPi_. This instal all supported operating systems. To install from PyPi you must first have the ``python`` and ``pip`` commands available on your -system. If you don't, see specific instructions for your operating system in this documentation on -how to get the Python environment set up. +system. If you are on Windows, and don't have Python installed, see :ref:`a_started_win_py` for +help. To install novelWriter from PyPi, use the following command: @@ -268,4 +243,35 @@ Make sure the install location for pip is in your PATH variable. This is not alw default. .. note:: + On systems with both Python 2 and 3, you may have to replace the ``pip`` command with ``pip3``. + + +.. _a_started_win_py: + +Installing Python on Windows +---------------------------- + +In order to run novelWriter from source, or install from PyPi, you need to have Python set up on +your system. Unlike Linux and MacOS, Windows does not come with Python pre-installed. + +You can download Python from `python.org`_. Python 3.7 or higher is required for running +novelWriter, but it is recommended that you install the latest version. + +Make sure you select the "Add Python to PATH" option during installation, otherwise the ``python`` +command will not work in the command line window. + +.. figure:: images/python_win_install.png + :align: center + :width: 500 + + Screenshot of the Python installer on Windows. + +When Python is installed, you should be able to run Python commands from the COmmand Prompt or +from PowerShell. You can verify this by running: + +.. code-block:: bash + + python --version + +This should print out the version number of the Python installation. From d78f13839e1754d8c66ff7e2a996abb95ebaa9ad Mon Sep 17 00:00:00 2001 From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com> Date: Mon, 13 Feb 2023 08:46:06 +0100 Subject: [PATCH 4/4] Clean up the gettings started document --- docs/source/int_started.rst | 126 ++++++------------------------------ 1 file changed, 18 insertions(+), 108 deletions(-) diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index c95e3827..3b7007f8 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -4,43 +4,35 @@ Getting Started *************** -.. _brew docs: https://docs.brew.sh/Homebrew-and-Python .. _Enchant: https://abiword.github.io/enchant/ .. _GitHub: https://github.com/vkbo/novelWriter -.. _macOS: https://github.com/vkbo/novelWriter/issues/867 .. _main website: https://novelwriter.io .. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter .. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre .. _PyPi: https://pypi.org/project/novelWriter/ .. _python.org: https://www.python.org/downloads/windows .. _Releases: https://github.com/vkbo/novelWriter/releases -.. _RPM: https://github.com/vkbo/novelWriter/issues/907 .. _AppImage: https://appimage.org/ -If you are using Windows or a Debian-based Linux distribtuion, you can install novelWriter from -package installers. If you are on macOS, you have the option to run novelWriter from a standalone -folder. See :ref:`a_started_minimal`. This option is also available for Windows and Linux. The -third option is to install novelWriter from the Python Package Index. See :ref:`a_started_pip`. +Package installers are available for all major platforms, including Linux, Windows and MacOS. See +below for install instructions for each platform. + +You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`. +Installing from PyPi does not set up icon launchers, so you will either have to do this yourself, +or start novelWriter from command line. Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it should pull dictionaries from your operating system automatically. However, on Windows they must be installed manually. See :ref:`a_custom_dict` for more details. -.. admonition:: Help Wanted - :class: seealso - - If you would like to help making more installers, the project is currently looking for people - who can help make releases for Red Hat-based Linux distros (RPM) and for macOS. See the issues - posted for RPM_ and macOS_ on GitHub_. - .. _a_started_windows: -Install on Windows -================== +Installing on Windows +===================== You can install novelWriter with both Python and library dependencies embedded using the Windows -Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub. +Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub_. Installing it should be straightforward. If you have any issues, try uninstalling the previous version and making a fresh install. If you @@ -49,10 +41,10 @@ already had a version installed via a different method, you should uninstall tha .. _a_started_linux: -Install on Linux -================ +Installing on Linux +=================== -A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub. +A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub_. This package should work on both Debian, Ubuntu and Linux Mint, at least. If you prefer, you can also add the novelWriter repository on Launchpad to your package manager. @@ -69,7 +61,7 @@ You can add the Ubuntu PPA_ and install novelWriter with the following commands. sudo apt update sudo apt install novelwriter -If you want pre-releases, add the ``ppa:vkbo/novelwriter-pre`` repository instead. +If you want the `Pre-Release PPA`_ instead, add the ``ppa:vkbo/novelwriter-pre`` repository. Debian and Mint @@ -108,11 +100,11 @@ They can of course be run on any Linux distro, if you prefer this to native pack .. _a_started_macos: -Install on MacOS -================ +Installing on MacOS +=================== You can install novelWriter with both its Python and library dependencies embedded using the DMG -application image file from the `main website`_, or from the Releases_ page on GitHub. Installing +application image file from the `main website`_, or from the Releases_ page on GitHub_. Installing it should be straightforward. * Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications` @@ -127,92 +119,10 @@ The context menu can also be accessed by option-clicking if you have a one butto done by holding down the option key on your keyboard and clicking on the application in Finder. -.. _a_started_minimal: - -Minimal Package Install -======================= - -On the `main website`_ and on the Releases_ page on GitHub you will also find "Minimal Package" -install files for Windows, Linux and macOS. These are zip files of just the files you need to run -novelWriter on that specific platform. - -These zip files don't include any dependencies, so you must install them separately. - - -.. _a_started_minimal_windows: - - - -.. _a_started_minimal_linux: - -Minimal Package on Linux ------------------------- - -On Linux you need to install the following packages on Debian-based distros, including Ubuntu and -Linux Mint: - -.. code-block:: bash - - sudo apt install python3-pyqt5 python3-lxml python3-enchant - -On Fedora, you need the following packages: - -.. code-block:: bash - - sudo dnf install python3-qt5 python3-lxml python3-enchant - -A standard desktop launcher can be installed via the main setup script. It will create the needed -desktop file and add it to the Applications menu. The necessary icons will also be installed, and a -file association with ``.nwx`` project files added. - -To set this up, run the following from inside the extracted novelWriter folder: - -.. code-block:: bash - - python3 setup.py xdg-install - -This installs icons for the current user. Run with ``sudo`` to install system-wide. - -To uninstall the icons, run: - -.. code-block:: bash - - python3 setup.py xdg-uninstall - - -.. _a_started_minimal_mac: - -Minimal Package on macOS ------------------------- - -These instructions assume you're using brew, and have Python and pip set up. If not, see the -`brew docs`_ for help. The main requirements for novelWriter are installed via the requirements -file. You also need to install the ``pyobjc`` package, so you should run: - -.. code-block:: bash - - pip3 install --user -r requirements.txt - pip3 install --user pyobjc - -For spell checking you may also need to install the enchant package. It comes with a lot of default -dictionaries. - -.. code-block:: bash - - brew install enchant - -With the dependencies in place, you can launch the ``novelWriter.py`` script directly to run -novelWriter. - -.. note:: - Right now there isn't a better integration with macOS available. Contributions from someone more - familiar with macOS would be very much appreciated. See the macOS_ issue on GitHub. - - .. _a_started_pip: -Install from PyPi -================= +Installing from PyPi +==================== novelWriter is also available on the Python Package Index, or PyPi_. This install method works on all supported operating systems.