Add customisation help to docs (#984)

* Make sure user-defined themes folders exist in the data path * Minor cleanup in shortcuts table * Add details in docs on how to customise GUI and add dictionaries * Add spell check reference in docs overview
vkbo · Feb 6, 2022 · 6d097f0 · 6d097f0
1 parent d7f2fec
commit 6d097f0
Show file tree

Hide file tree

Showing 7 changed files with 164 additions and 12 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -54,6 +54,7 @@ too. novelWriter can be run directly from the Python source, installed from the
    int_overview
    int_started
    int_source
+   int_customise
 
 .. toctree::
    :maxdepth: 1
@@ -82,5 +83,6 @@ too. novelWriter can be run directly from the Python source, installed from the
    :caption: Under the Hood
    :hidden:
 
+   tech_locations
    tech_storage
    tech_tests
diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst
@@ -0,0 +1,74 @@
+.. _a_custom:
+
+**************
+Customisations
+**************
+
+There are a few ways you can customise novelWriter youself. Currently, you can add new GUI themes,
+your own syntax themes, and install additional dictionaries.
+
+
+.. _a_custom_dict:
+
+Spell Check Dictionaries
+========================
+
+novelWriter uses `Enchant <https://abiword.github.io/enchant/>`_ as the spell checking tool.
+Depending on you operating system, it may or may not load installed spell check dictionaries.
+
+Linux
+   On Linux, you generally only have to install hunspell or aspell dictionaries on your system like
+   you do for other applications. See your distro's documentation for how to do this.
+
+Windows
+   For Windows, English is included with the installation. For other languages you have to download
+   and add dictionaries yourself. You can find the various dictionaries on the
+   `Free Desktop <https://cgit.freedesktop.org/libreoffice/dictionaries/tree/>`_ website. You should
+   find a folder for your language, if it is available at all, and download the files ending with
+   ``.aff`` and ``.dic``. These files must then be copied to the following location:
+
+   ``C:\Users\<USER>\AppData\Local\enchant\hunspell``
+
+   This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or two folders may
+   not exist, so you may need to create them.
+
+
+.. _a_custom_theme:
+
+Syntax and GUI Themes
+=====================
+
+Adding your own GUI and syntax themes is relatively easy. The themes are defined by simple plain
+text config files with meta data and colour settings.
+
+In order to make your own versions, first copy one of the existing files to your local computer and
+modify it as you like.
+
+* The existing syntax themes are stored in
+  `novelwriter/assets/syntax <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/syntax>`_.
+* The existing GUI themes are stored in
+  `novelwriter/assets/themes <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/themes>`_.
+
+Remember to also change the name of your theme by modifying the ``name`` setting at the top of the
+file.
+
+For novelWriter to locate the custom theme files, you must copy them to the :ref:`a_locations_data`
+location in your home or user area. There should be a folder there named ``syntax`` for syntax
+themes and just ``themes`` for GUI themes.
+
+Once the files are copied there, they should show up in :guilabel:`Preferences` with the label you
+set as ``name`` inside the file.
+
+Theme CSS Files
+---------------
+
+If you wish, you can also modify the CSS styles of the GUI in addition to change colour settings.
+This is only available for GUI themes, and you do this by creating a file with the exact same file
+name as the ``.conf`` file with colour settings and give it the ``.qss`` extension.
+
+On Windows, file extensions may not be visible by default, so make sure you only have one file
+extension, and don't end up with two.
+
+The QSS files are Qt Style Sheet files. See Qt's
+`The Style Sheet Syntax <https://doc.qt.io/qt-5/stylesheet-syntax.html>`_` documentation for more
+details.
diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst
@@ -21,6 +21,8 @@ applications.
 
 For install instructions, see :ref:`a_started`.
 
+For information on how to add spell check dictionaries, see :ref:`a_custom_dict`.
+
 Using novelWriter
 =================
 

diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst
@@ -4,22 +4,27 @@
 Getting Started
 ***************
 
+.. _brew docs: https://docs.brew.sh/Homebrew-and-Python
+.. _Enchant: https://abiword.github.io/enchant/
 .. _GitHub: https://github.com/vkbo/novelWriter
-.. _Releases: https://github.com/vkbo/novelWriter/releases
-.. _RPM: https://github.com/vkbo/novelWriter/issues/907
 .. _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
-.. _python.org: https://www.python.org/downloads/windows
-.. _brew docs: https://docs.brew.sh/Homebrew-and-Python
 .. _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
 
 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`.
 
+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
 

diff --git a/docs/source/tech_locations.rst b/docs/source/tech_locations.rst
@@ -0,0 +1,57 @@
+.. _a_locations:
+
+**************
+File Locations
+**************
+
+.. _QStandardPaths: https://doc.qt.io/qt-5/qstandardpaths.html
+
+novelWriter will create a few files on your system outside of the application folder itself. These
+file locations are described in this document.
+
+
+.. _a_locations_conf:
+
+Configuration
+=============
+
+The general configuration of novelWriter, including everything that is in :guilabel:`Preferences`,
+is saved in one central configuration file. The location of this file depends on your operating
+system. The system paths are provided by the Qt QStandardPaths_ class and its ConfigLocation value.
+
+The standard paths are:
+
+* Linux: ``~/.config/novelwriter/novelwriter.conf``
+* macOS: ``~/Library/Preferences/novelwriter/novelwriter.conf``
+* Windows: ``C:\Users\<USER>\AppData\Local\novelwriter\novelwriter.conf``
+
+Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ``<USER>`` is the
+user's username on Windows.
+
+.. note::
+   These are the standard operating system defined locations. If your system has been set up in a
+   different way, these locations may also be different.
+
+
+.. _a_locations_data:
+
+Application Data
+================
+
+novelWriter also stores a bit of data that is generated by the user's actions. This includes the
+list of recent projects form the :guilabel:`Open Project` dialog. Custom themes are also saved
+here. The system paths are provided by the Qt QStandardPaths_ class and its AppDataLocation value
+on Qt 5.4 or greater, or DataLocation for earlier versions.
+
+The standard paths are:
+
+* Linux: ``~/.local/share/novelwriter/``
+* macOS: ``~/Library/Application Support/novelwriter/``
+* Windows: ``C:\Users\<USER>\AppData\Roaming\novelwriter\``
+
+Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ``<USER>`` is the
+user's username on Windows.
+
+.. note::
+   These are the standard operating system defined locations. If your system has been set up in a
+   different way, these locations may also be different.
diff --git a/docs/source/usage_shortcuts.rst b/docs/source/usage_shortcuts.rst
@@ -16,7 +16,7 @@ The main shorcuts are as follows:
 
 .. csv-table:: Keyboard Shortcuts
    :header: "Shortcut", "Description"
-   :widths: 25, 75
+   :widths: 20, 80
    :class: "tight-table"
 
    ":kbd:`Alt`:kbd:`1`",                 "Switch focus to the project tree. On Windows, use :kbd:`Ctrl`:kbd:`Alt`:kbd:`1`."
@@ -42,9 +42,9 @@ The main shorcuts are as follows:
    ":kbd:`Ctrl`:kbd:`B`",                "Format selected text, or word under cursor, with strong emphasis (bold)."
    ":kbd:`Ctrl`:kbd:`C`",                "Copy selected text to clipboard."
    ":kbd:`Ctrl`:kbd:`D`",                "Strikethrough selected text, or word under cursor."
-   ":kbd:`Ctrl`:kbd:`E`",                "If in the project tree, edit a document or folder settings. (Same as :kbd:`F2`.)"
+   ":kbd:`Ctrl`:kbd:`E`",                "If in the project tree, edit a document or folder settings."
    ":kbd:`Ctrl`:kbd:`F`",                "Open the search bar and search for the selected word, if any is selected."
-   ":kbd:`Ctrl`:kbd:`G`",                "Find next occurrence of search word in current document. (Same as :kbd:`F3`.)"
+   ":kbd:`Ctrl`:kbd:`G`",                "Find next occurrence of search word in current document."
    ":kbd:`Ctrl`:kbd:`H`",                "Open the search and replace bar and search for the selected word, if any is selected. (On Mac, this is :kbd:`Cmd`:kbd:`=`.)"
    ":kbd:`Ctrl`:kbd:`I`",                "Format selected text, or word under cursor, with emphasis (italic)."
    ":kbd:`Ctrl`:kbd:`K`",                "Activate the insert commands. The commands are listed in :ref:`a_kb_ins`."
@@ -71,7 +71,7 @@ The main shorcuts are as follows:
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`/`",    "Remove block formatting for block under cursor."
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`1`",    "Replace occurrence of search word in current document, and search for next occurrence."
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`A`",    "Select all text in current paragraph."
-   ":kbd:`Ctrl`:kbd:`Shift`:kbd:`G`",    "Find previous occurrence of search word in current document. (Same as :kbd:`Shift`:kbd:`F3`.)"
+   ":kbd:`Ctrl`:kbd:`Shift`:kbd:`G`",    "Find previous occurrence of search word in current document."
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`I`",    "Import text to the current document from a text file."
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`N`",    "Create new folder."
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`O`",    "Open a project."
@@ -81,8 +81,8 @@ The main shorcuts are as follows:
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`",    "Undo move of project tree item."
    ":kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`",  "If in the project tree, move a document to trash, or delete a folder."
    ":kbd:`F1`",                          "Open the online user manual."
-   ":kbd:`F2`",                          "If in the project tree, edit a document or folder settings. (Same as :kbd:`Ctrl`:kbd:`E`)"
-   ":kbd:`F3`",                          "Find next occurrence of search word in current document. (Same as :kbd:`Ctrl`:kbd:`G`)"
+   ":kbd:`F2`",                          "If in the project tree, edit a document or folder settings."
+   ":kbd:`F3`",                          "Find next occurrence of search word in current document."
    ":kbd:`F5`",                          "Open the :guilabel:`Build Novel Project` dialog."
    ":kbd:`F6`",                          "Open the :guilabel:`Writing Statistics` dialog."
    ":kbd:`F7`",                          "Re-run spell checker."
@@ -91,7 +91,7 @@ The main shorcuts are as follows:
    ":kbd:`F10`",                         "Re-build the project outline."
    ":kbd:`F11`",                         "Activate full screen mode."
    ":kbd:`Shift`:kbd:`F1`",              "Open the local user manual (PDF) if it is available."
-   ":kbd:`Shift`:kbd:`F3`",              "Find previous occurrence of search word in current document. (Same as :kbd:`Ctrl`:kbd:`Shift`:kbd:`G`.)"
+   ":kbd:`Shift`:kbd:`F3`",              "Find previous occurrence of search word in current document."
    ":kbd:`Shift`:kbd:`F6`",              "Open the :guilabel:`Project Details` dialog."
    ":kbd:`Return`",                      "If in the project tree, open a document for editing."
 
@@ -110,7 +110,7 @@ a key or key combination for the inserted content.
 
 .. csv-table:: Keyboard Shortcuts
    :header: "Shortcut", "Description"
-   :widths: 25, 75
+   :widths: 30, 70
    :class: "tight-table"
 
    ":kbd:`Ctrl`:kbd:`K`, :kbd:`−`",                 "Insert a short dash (en dash)."

diff --git a/novelwriter/config.py b/novelwriter/config.py
@@ -278,6 +278,18 @@ def initConfig(self, confPath=None, dataPath=None):
         logger.verbose("Config path: %s", self.confPath)
         logger.verbose("Data path: %s", self.dataPath)
 
+        # Check Data Path Subdirs
+        dataDirs = ["syntax", "themes"]
+        for dataDir in dataDirs:
+            dirPath = os.path.join(self.dataPath, dataDir)
+            if not os.path.isdir(dirPath):
+                try:
+                    os.mkdir(dirPath)
+                    logger.info("Created folder: %s", dirPath)
+                except Exception:
+                    logger.error("Could not create folder: %s", dirPath)
+                    logException()
+
         self.confFile = self.appHandle+".conf"
         self.lastPath = os.path.expanduser("~")
         self.appPath = getattr(sys, "_MEIPASS", os.path.abspath(os.path.dirname(__file__)))