From 704103f9f14a574c51c5d8877f33feb74e68973e Mon Sep 17 00:00:00 2001 From: "Veronica K. B. Olsen" <1619840+vkbo@users.noreply.github.com> Date: Mon, 1 Feb 2021 17:12:59 +0100 Subject: [PATCH] Reorganised and update install instruction in the docs --- docs/source/_static/css/custom.css | 4 + docs/source/index.rst | 19 +- docs/source/int_introduction.rst | 4 +- docs/source/int_linux.rst | 75 ++++++ docs/source/int_mac.rst | 66 +++++ docs/source/int_started.rst | 245 ++++-------------- docs/source/int_windows.rst | 91 +++++++ .../{write_export.rst => usage_export.rst} | 0 ...{int_interface.rst => usage_interface.rst} | 0 .../{write_notes.rst => usage_notes.rst} | 0 ...{write_projects.rst => usage_projects.rst} | 0 ...rite_structure.rst => usage_structure.rst} | 0 ...nt_typography.rst => usage_typography.rst} | 0 nw/gui/mainmenu.py | 6 +- win_install.bat | 4 + 15 files changed, 306 insertions(+), 208 deletions(-) create mode 100644 docs/source/int_linux.rst create mode 100644 docs/source/int_mac.rst create mode 100644 docs/source/int_windows.rst rename docs/source/{write_export.rst => usage_export.rst} (100%) rename docs/source/{int_interface.rst => usage_interface.rst} (100%) rename docs/source/{write_notes.rst => usage_notes.rst} (100%) rename docs/source/{write_projects.rst => usage_projects.rst} (100%) rename docs/source/{write_structure.rst => usage_structure.rst} (100%) rename docs/source/{int_typography.rst => usage_typography.rst} (100%) create mode 100644 win_install.bat diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index 683ca054..fb2f9582 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -21,3 +21,7 @@ white-space: normal !important; vertical-align: text-top; } + +pre span.go { + color: #333333 !important; +} diff --git a/docs/source/index.rst b/docs/source/index.rst index 1fc44954..41c485dd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -57,22 +57,25 @@ details. .. toctree:: :maxdepth: 2 - :caption: First Steps + :caption: Introduction int_introduction int_started - int_interface - int_typography + int_linux + int_mac + int_windows .. toctree:: :maxdepth: 2 - :caption: Writing Novels + :caption: Usage - write_projects - write_structure - write_notes - write_export + usage_interface + usage_projects + usage_structure + usage_notes + usage_export + usage_typography .. toctree:: diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst index a1a97159..4e827724 100644 --- a/docs/source/int_introduction.rst +++ b/docs/source/int_introduction.rst @@ -42,8 +42,8 @@ formatting features supported are available through convenient keyboard shortcut available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts` section. -In addition, novelWriter offers a :guilabel:`Distraction Free Mode` where all the user interface -elements other than the document editor itself are hidden away. +In addition, novelWriter offers a :guilabel:`Focus Mode` where all the user interface elements +other than the document editor itself are hidden away. The colour scheme of the user interface defaults to that of the host operating system. In addition, a dark theme is provided, and can be enabled in :guilabel:`Preferences` from the :guilabel:`Tools` diff --git a/docs/source/int_linux.rst b/docs/source/int_linux.rst new file mode 100644 index 00000000..37267d45 --- /dev/null +++ b/docs/source/int_linux.rst @@ -0,0 +1,75 @@ +.. _a_setup_linux: + +************** +Setup on Linux +************** + +.. _GitHub: https://github.com/vkbo/novelWriter/releases +.. _main website: https://novelwriter.io + +This is a brief guide to how you can get novelWriter running on a Linux computer. There are +currently no packaged version of novelWriter for Linux, so it is recommended that you just extract +the source to a practical location on your system and run the ``setup.py`` script. + + +Running from Source +=================== + +To run novelWriter from source, download the latest source package from the release page on +GitHub_ or the `main website`_, or if you have git running on your computer, you can also clone the +repository. + + +Step 1: Installing Dependencies +------------------------------- + +The dependencies of novelWriter are generally available from Linux distro repositories. For Debian +and Ubuntu, they can be installed with: + +.. code-block:: console + + sudo apt install python3-pyqt5 python3-lxml python3-enchant + +If you prefer to install dependencies via PyPi, or the repository dependencies are out of date, you +can install them with: + +.. code-block:: console + + pip3 install --user -r requirements.txt + + +Step 2: Install Package (Optional) +---------------------------------- + +You can install novelWriter to the correct location for Python packages with: + +.. code-block:: console + + ./setup.py install + +This is equivalent to what the ``pip`` installer does. It puts novelWriter in the location on your +system where Python packages are usually kept. This is not really the best suited location for a +GUI application like novelWriter, so you may instead copy the entire source to a suiteable location +yourself. + +By default, this command installs novelWriter for the current user only. To install for all users, +run the script with the ``sudo`` command. + +This should install novelWriter to either ``~/.local/bin/novelWriter`` if installed for local user +only, or to ``/usr/local/bin/novelWriter`` if installed for all users. + + +Step 3: Create Launcher Icons +----------------------------- + +To set up the novelWriter desktop launcher, the icons, and the project file association, run: + +.. code-block:: console + + ./setup.py xdg-install + +By default, these commands install novelWriter and its icons for the current user only. To install +for all users, run the script with the ``sudo`` command. + +.. tip:: + All options of the setup script can be listed with: ``./setup.py help``. diff --git a/docs/source/int_mac.rst b/docs/source/int_mac.rst new file mode 100644 index 00000000..e338f02a --- /dev/null +++ b/docs/source/int_mac.rst @@ -0,0 +1,66 @@ +.. _a_setup_mac: + +************** +Setup on macOS +************** + +.. _GitHub: https://github.com/vkbo/novelWriter/releases +.. _main website: https://novelwriter.io +.. _brew docs: https://docs.brew.sh/Homebrew-and-Python + +This is a brief guide to how you can get novelWriter running on macOS. There are currently no +packaged version of novelWriter for macOS, so it is recommended that you just extract the source to a +practical location on your system and run it. + + +Running from Source +=================== + +To run novelWriter from source, download the latest source package from the release page on +GitHub_ or the `main website`_, or if you have git running on your computer, you can also clone the +repository. + + +Step 1: Installing Dependencies +------------------------------- + +These instructions assume you're using brew, and have Python and pip set up. If not, see the +`brew docs`_ for help. Main requirements are installed via the requirements file. You also need to +install the ``pyobjc`` package, so you should run: + +.. code-block:: console + + 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:: console + + brew install enchant + +With the dependencies in place, you can launch the ``novelWriter.py`` script directly to run +novelWriter. + + +Step 2: Install Package (Optional) +---------------------------------- + +You can install novelWriter to the correct location for Python packages with: + +.. code-block:: console + + ./setup.py install + +This is equivalent to what the ``pip`` installer does. It puts novelWriter in the location on your +system where Python packages are usually kept. This is not really the best suited location for a +GUI application like novelWriter, so you may instead copy the entire source to a suiteable location +yourself. + +After this, you should be able to launch novelWriter by running ``novelWriter`` in a command line +window. + +.. note:: + Right now there isn't a better integration with macOS available. Contributions from someone more + familiar with macOS would be very much appreciated. diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index 8ae9c4c6..4feb9c8c 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -4,14 +4,22 @@ Getting Started *************** -This is a brief guide to how you can get novelWriter running on your computer. These are the -methods currently supported by the developer. Packages may also be available in other package -managers, but those are not managed by the developer. A Windows installer file is also provided on -the GitHub releases page and linked from the `main website`_. +.. _main website: https://novelwriter.io +.. _GitHub: https://github.com/vkbo/novelWriter/releases +.. _PyPi: https://pypi.org/project/novelWriter/ + +This section contains brief guides to how you can get novelWriter running on your computer. These +are the methods currently supported by the developer. Packages may also be available in other +package managers, but those are not managed by the developer. A Windows installer file is also +provided on the GitHub_ releases page and linked from the `main website`_. As novelWriter matures, more options for how to install it and get it running will be added. For non-Windows users the install process is at the present time best suited for people used to working -with the command line. But even if you're not, the install process is fairly straight forward. +with the command line. But even if you're not, the install process is fairly straightforward. + +The next pages have specific install instructions for the various operating systems novelWriter can +run on. The instructions below are supplementary information, instructions for alterbative methods, +and additional build options. .. note:: The text below assumes the command ``python`` corresponds to a Python 3 executable. For @@ -19,13 +27,47 @@ with the command line. But even if you're not, the install process is fairly str Linux, the scripts can also be made executable and run without the ``python`` command. Likewise, ``pip`` may need to be replaced with ``pip3``. -.. _main website: https://novelwriter.io + +.. _a_started_depend: + +Dependencies +============ + +novelWriter has been designed to rely on as few dependencies as possible. Aside from the packages +needed to communicate with the Qt GUI libraries, only one package is required for handling the XML +format of the main project file. Everything else is handled with standard Python libraries. + +The following Python packages are needed to run novelWriter: + +* ``pyqt5`` – needed for connecting with the Qt5 libraries. +* ``lxml`` – needed for full XML support. +* ``pyenchant`` – needed for efficient spell checking (optional). + +PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work. +Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular +expressions requires 5.3, and for full Unicode support, 5.13. There is no known minimum version +requirement for package ``lxml``, but the code was originally written with 4.2, which is therefore +set as the minimum. It may work on lower versions. You have to test it. + +Optionally, a package can be installed to interface with the Enchant spell checking libaries, but +this isn't strictly required. If no external spell checking library is available, novelWriter falls +back to using the internal ``difflib`` of Python to check spelling. This is a much slower approach, +and it is less sophisticated than full spell checking libaries, but if you only work with small +files, the performance loss is not noticeable. The spell check library must be at least 3.0 to work +with Windows. On Linux, 2.0 also works fine. + +If you install from PyPi, these dependencies should be installed automatically. If you install from +source, dependencies can still be installed from PyPi with: + +.. code-block:: console + + pip install -r requirements.txt .. _a_started_install: -Installing and Running -====================== +Installing via PyPi +=================== The application is written in Python 3 using Qt5 via PyQt5. It is developed on Linux, but it should in principle work fine on other operating systems as long as dependencies are met. @@ -58,193 +100,6 @@ When installing via pip, novelWriter can be launched from command line with: Make sure the install location for pip is in your PATH variable. This is not always the case by default. -.. _GitHub: https://github.com/vkbo/novelWriter/releases -.. _PyPi: https://pypi.org/project/novelWriter/ - - -.. _a_started_depend: - -Python Dependencies -------------------- - -novelWriter has been designed to rely on as few dependencies as possible. Aside from the package(s) -needed to communicate with the Qt GUI libraries, only one package is required for handling the XML -format of the main project file. Everything else is handled with standard Python libraries. - -The following Python packages are needed to run novelWriter: - -* ``pyqt5`` – needed for connecting with the Qt5 libraries. -* ``lxml`` – needed for full XML support. -* ``pyenchant`` – needed for efficient spell checking (optional). - -PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work. -Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular -expressions requires 5.3, and for full Unicode support, 5.13. There is no known minimum version -requirement for package ``lxml``, but the code was originally written with 4.2, which is therefore -set as the minimum. It may work on lower versions. You have to test it. - -Optionally, a package can be installed to interface with the Enchant spell checking libaries, but -this isn't strictly required. If no external spell checking library is available, novelWriter falls -back to using the internal ``difflib`` of Python to check spelling. This is a much slower approach, -and it is less sophisticated than full spell checking libaries, but if you only work with small -files, the performance loss is not noticeable. The spell check library must be at least 3.0 to work -with Windows. On Linux, 2.0 also works fine. - -If you install from PyPi, these dependencies should be installed automatically. If you install from -source, dependencies can still be installed from PyPi with: - -.. code-block:: console - - pip install -r requirements.txt - - -.. _a_started_running: - -Running from Source -------------------- - -If all the required dependencies are met, you can run novelWriter from the command line with: - -.. code-block:: console - - python novelWriter.py - -A few switches are supported from the command line, mostly to assist in debugging if an error is -encountered. To list all options, run: - -.. code-block:: console - - python novelWriter.py --help - - -.. _a_started_linux: - -Setup on Linux -============== - -The dependencies of novelWriter are generally available from Linux distro repositories. For Debian -and Ubuntu, they can be installed with: - -.. code-block:: console - - sudo apt install python3-pyqt5 python3-lxml python3-enchant - -If you downloaded the source, you can use the provided ``setup.py`` script to install novelWriter -into the system's default Python install locations. If so, run: - -.. code-block:: console - - python setup.py install - -To set up the novelWriter desktop launcher, the icons, and the project file association, run: - -.. code-block:: console - - python setup.py xdg-install - -By default, these commands install novelWriter and its icons for the current user only. To install -for all users, run the script with the ``sudo`` command. Other options are also available. Run -``python setup.py help`` for a full list of install options. - -This should install novelWriter to either ``~/.local/bin/novelWriter`` if installed for local user -only, or to ``/usr/local/bin/novelWriter`` if installed for all users. - - -.. _a_started_macos: - -Setup on macOS -============== - -These instructions assume you're using brew, and have Python and pip set up. If not, see the -`brew docs`_ for help. Main requirements are installed via the requirements file. You also need to -install the ``pyobjc`` package, so you must run: - -.. code-block:: console - - 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:: console - - brew install enchant - -With the dependencies in place, you can either launch the ``novelWriter.py`` script directly, or -run the install command: - -.. code-block:: console - - python setup.py install - -After this, you should be able to launch novelWriter by running ``novelWriter`` in a command line -window. - -Right now there isn't a better integration with macOS available. Contributions from someone more -familiar with macOS would be very much appreciated. - -.. _brew docs: https://docs.brew.sh/Homebrew-and-Python - - -.. _a_started_windows: - -Setup on Windows -================ - -On Windows, you have two options: You can either run from source, or install novelWriter via a -Windows installer. - - -.. _a_started_win_installer: - -Windows Installer ------------------ - -You can install novelWriter with the Windows installer for 64-bit Windows available on the -`main website`_ and GitHub_ page. This installer bundles all that is needed for novelWriter to run, -including Python and the XML and Qt libraries. When installing novelWriter this way, you don't need -to install any of the dependencies manually. The installer is made with pyinstaller and Inno Setup. - - -.. _a_started_win_source: - -From Source ------------ - -To run from source, you may first need to install Python. If you don't have it installed, you can -download it from the python.org_ website. novelWriter should work with Python 3.6 or higher, but it -is recommended that you install the latest version of Python. - -Also, make sure you select the "Add Python to PATH" option during installation, otherwise the -``python`` command will not work in the command line window. - -.. image:: images/python_win_install.png - :width: 600 - -Once Python is set up and running, you can either run novelWriter from the folder where you -extracted it, or you can build an executable and run that from a desktop icon instead. - -The PyPi installer should come bundled with the Python installation, so to install dependencies, -run: - -.. code-block:: console - - pip install --user -r requirements.txt - -.. tip:: - - To create a desktop shortcut to launch novelWriter, you can right click the ``novelWriter.py`` - file, create a shortcut, then right click again, select "Properties" and change the target to - your python executable followed by ``novelWriter.py``. It should look something like this: - ``C:\...\AppData\Local\Programs\Python\Python38\python.exe novelWriter.py`` - -You can also run the ``setup.py`` script to generate a single executable, or an installer. -See `Build and Install novelWriter`_ for more details or run: ``python setup.py help``. - -.. _python.org: https://www.python.org/downloads/windows/ -.. _Build and Install novelWriter: https://github.com/vkbo/novelWriter/blob/main/setup/README.md - .. _a_started_docs: diff --git a/docs/source/int_windows.rst b/docs/source/int_windows.rst new file mode 100644 index 00000000..4b2e164c --- /dev/null +++ b/docs/source/int_windows.rst @@ -0,0 +1,91 @@ +.. _a_setup_win: + +**************** +Setup on Windows +**************** + +.. _GitHub: https://github.com/vkbo/novelWriter/releases +.. _main website: https://novelwriter.io +.. _zipapp: https://docs.python.org/3/library/zipapp.html +.. _Inno Setup: https://jrsoftware.org/isinfo.php +.. _python.org: https://www.python.org/downloads/windows +.. _PyPi: https://pypi.org/project/novelWriter +.. _discussions: https://github.com/vkbo/novelWriter/discussions + +This is a brief guide to how you can get novelWriter running on a Windows computer. + +On Windows, you have two options: You can either run from source, or install novelWriter via a +Windows installer. The latter is the simplest, but since novelWriter is a hobby project, the +installer is not signed and downloading and running the installer often triggers warning because +Windows doesn't know whether it's safe or not. + +The installer contains an executable zip of novelWriter, a copy of the three libraries it depends +on, and a copy of the Python run environment. If you're uncomfortable with running this installer, +you can install the components yourself and just run novelWriter directly from the source code. The +Source code can be downloaded as a zip file directly from GitHub_. + + +.. _a_setup_win_installer: + +Using the Installer +=================== + +You can install novelWriter with the Windows installer for 64-bit Windows available on the +`main website`_ and GitHub_ page. This installer bundles all that is needed for novelWriter to run, +including Python and the XML and Qt libraries. When installing novelWriter this way, you don't need +to install any of the dependencies manually. The installer is made with zipapp_ and `Inno Setup`_. + + +.. _a_setup_win_source: + +Running from Source +=================== + +To run novelWriter from source, download the latest source package from the release page on +GitHub_, or if you have git running on your computer, you can also clone the repository. + +The main requirement is that you have Python installed. The dependencies of novelWriter can then be +installed from the Python Package Index, PyPi_. + +Step 1: Installing Python +------------------------- + +If you already have Python installed, you can skip this step. If you don't have it installed, you +can download it from the python.org_ website. novelWriter should work with Python 3.6 or higher, +but it is recommended that you install the latest version of Python. + +Also, make sure you select the "Add Python to PATH" option during installation, otherwise the +``python`` command will not work in the command line window. + +.. image:: images/python_win_install.png + :width: 600 + +Step 2: Dependencies and Icons +------------------------------ + +**Alternative A: By Script** + +Open the folder where you extracted the novelWriter source, and double-click the file named +``win_install`` or ``win_install.bat``. This should open a command line window and run the setup +script to install dependencies and desktop and start menu icons. + +**Alternative B: Command Prompt** + +The above alternative can also be run manually. + +Open the windows command prompt. It can be launched by pressing the :kbd:`Win` key and typing "cmd". +The "Command Prompt" app should then be in the list of applications. + +With the command prompt open, navigate to the folder where you extracted the novelWriter source, +and run the following commands. + +.. code-block:: console + + python setup.py pip + python setup.py win-install + +The first command will install the dependencies on your system, and the second command will create +a desktop icon and a start menu icon. + +That should be all that you need. If you have any problems, you can always open a question on the +project's discussions_ page. This requires a GitHub account. diff --git a/docs/source/write_export.rst b/docs/source/usage_export.rst similarity index 100% rename from docs/source/write_export.rst rename to docs/source/usage_export.rst diff --git a/docs/source/int_interface.rst b/docs/source/usage_interface.rst similarity index 100% rename from docs/source/int_interface.rst rename to docs/source/usage_interface.rst diff --git a/docs/source/write_notes.rst b/docs/source/usage_notes.rst similarity index 100% rename from docs/source/write_notes.rst rename to docs/source/usage_notes.rst diff --git a/docs/source/write_projects.rst b/docs/source/usage_projects.rst similarity index 100% rename from docs/source/write_projects.rst rename to docs/source/usage_projects.rst diff --git a/docs/source/write_structure.rst b/docs/source/usage_structure.rst similarity index 100% rename from docs/source/write_structure.rst rename to docs/source/usage_structure.rst diff --git a/docs/source/int_typography.rst b/docs/source/usage_typography.rst similarity index 100% rename from docs/source/int_typography.rst rename to docs/source/usage_typography.rst diff --git a/nw/gui/mainmenu.py b/nw/gui/mainmenu.py index 554eca52..a7087aa8 100644 --- a/nw/gui/mainmenu.py +++ b/nw/gui/mainmenu.py @@ -478,9 +478,9 @@ class GuiMainMenu(QMenuBar): # View > Separator self.viewMenu.addSeparator() - # View > Toggle Distraction Free Mode - self.aFocusMode = QAction("Distraction Free Mode", self) - self.aFocusMode.setStatusTip("Toggles distraction free mode, only showing text editor") + # View > Focus Mode + self.aFocusMode = QAction("Focus Mode", self) + self.aFocusMode.setStatusTip("Toggles a distraction free mode, only showing text editor") self.aFocusMode.setShortcut("F8") self.aFocusMode.setCheckable(True) self.aFocusMode.setChecked(self.theParent.isFocusMode) diff --git a/win_install.bat b/win_install.bat new file mode 100644 index 00000000..b36dab22 --- /dev/null +++ b/win_install.bat @@ -0,0 +1,4 @@ +@echo off +python setup.py pip +python setup.py win-install +pause