From 9f766e6a08f7e7a84c5f2df99ab1c1d652b4be3e Mon Sep 17 00:00:00 2001 From: facelessuser Date: Mon, 1 Jan 2024 19:11:09 -0700 Subject: [PATCH] Update docs --- mkdocs-internal.yml | 4 +- mkdocs.yml | 4 +- rummage/lib/gui/data/docs/.dochash | 2 +- rummage/lib/gui/data/docs/installation.html | 138 ++++++++++++-------- 4 files changed, 88 insertions(+), 60 deletions(-) diff --git a/mkdocs-internal.yml b/mkdocs-internal.yml index e8a9f453..e1a1ec07 100644 --- a/mkdocs-internal.yml +++ b/mkdocs-internal.yml @@ -55,8 +55,8 @@ markdown_extensions: - pymdownx.caret: - pymdownx.smartsymbols: - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.escapeall: hardbreak: True nbsp: True diff --git a/mkdocs.yml b/mkdocs.yml index aaa59204..eddf2873 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -82,8 +82,8 @@ markdown_extensions: - pymdownx.caret: - pymdownx.smartsymbols: - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.escapeall: hardbreak: True nbsp: True diff --git a/rummage/lib/gui/data/docs/.dochash b/rummage/lib/gui/data/docs/.dochash index afd74dcb..102d15f3 100644 --- a/rummage/lib/gui/data/docs/.dochash +++ b/rummage/lib/gui/data/docs/.dochash @@ -1 +1 @@ -b878f7fc01c2d39369a4c95697d6fda1 \ No newline at end of file +e368ff97e0f58e65729edb321f838cb6 \ No newline at end of file diff --git a/rummage/lib/gui/data/docs/installation.html b/rummage/lib/gui/data/docs/installation.html index 8ee7fa45..d6be31ad 100644 --- a/rummage/lib/gui/data/docs/installation.html +++ b/rummage/lib/gui/data/docs/installation.html @@ -41,32 +41,44 @@
  • Installation
    • @@ -94,18 +106,10 @@

    Requirements

    Installation

    -

    On systems like Windows, installation is pretty straight forward as wheels are provided for all packages in pip. On -other systems, there may be some prerequisites. If on Linux, it is recommended to make sure you can install wxpython -first. This is due to the fact that installation of that library may require special instructions and will cause the -installation of Rummage to fail if wxpython fails due to not having the necessary prerequisites.

    -
    -

    Prerequisites

    - -
    -

    Assuming prerequisites are satisfied, installing Rummage is easy.

    +

    For well supported platforms, Python wheels are usually available for Rummage and its dependencies. In most cases, +installation can be done quickly and easily through pip. Some platforms, like Linux, may require some additional +hoops that you must jump through. Additionally, wxPython, the GUI library that Rummage depends on, may sometimes have +support lagging for the latest Python version.

    Install:

    $ pip install rummage
    @@ -115,25 +119,61 @@

    Installation

    Upgrade:

    $ pip install --upgrade rummage
    -

    Linux Prerequisites

    -

    Linux is by far the more involved system to install wxPython on, but it is getting easier.

    - -

    Pre-built Wheels

    -

    The wxPython project has started providing wheels for certain distros. While not all distros have wheels, this may -be an attractive solution if you run one of the distros that do have pre-built wheels. The one downside is that the -wheels are not available through on PyPI. More information on why and details on installation can be found here: -https://www.wxpython.org/pages/downloads/.

    -

    Simplified instructions:

    -
      -
    1. -

      Find the folder for your distro over at https://extras.wxpython.org/wxPython4/extras/linux/.

      -
      2. -
    2. -

      Use pip and the server's location like so.

      +

      Windows

      +

      On systems like Windows, installation is pretty straight forward as wheels are provided for all packages in pip. +Support for the latest Python version may not always be available as the development cycle for wxPython can take a bit +to catch up.

      +

      Simply using pip to install is sufficient.

      +
      $ pip install rummage
+
      +

      MacOS

      +

      In recent years, wheels are usually available for wxPython on macOS. Support for the latest Python version may not +always be available as the development cycle for wxPython can take a bit to catch up.

      +

      Usually, you can just use pip to install:

      +
      $ pip install rummage
+
      +

      Linux

      +

      Linux doesn't often have pre-built wheels for wxPython, so often, you must first ensure some prerequisites are in place +before using pip install (or other methods). Additionally, Linux, in recent years, has made managing libraries and +applications in Python a bit more complex with its new restrictions. Despite all of this, Rummage is still supported, +but may require slightly more complex installation.

      +

      pipx

      +

      If installing Rummage on Linux, you may consider pipx, especially if your distro has a new enough wxPython distro +packages. On Ubuntu, installation may look similar to the following:

      +
      $ sudo apt install python3-wgtk4.0 python3-wxgtk-webview4.0
+$ pipx install --system-site-packages rummage
+
      +

      The --system-site-packages flag is necessary as by default, pipx will create a brand new virtual environment that +does not have access to the globally available distro package.

      +

      venv

      +

      Another approach on Linux is to use the venv package to install Rummage and its dependencies. If your distro has a new +enough wxPython distro package, you can install the wxPython and then create your virtual +environment with the --system-site-packages flag to ensure it has access to the installed package. On Ubuntu, it may +look similar to:

      +
      $ sudo apt install python3-wgtk4.0 python3-wxgtk-webview4.0
+$ python3 -m venv --system-site-packages ./venv/rummage
+$ source ./venv/rummage/bin/activate
+$ (rummage) $ pip install rummage
+
      +

      If your distro does not have a proper wxPython package, you may have to install it from another source under your +virtual environment.

      +

      Prerequisites

      +

      The most important prerequisite to getting Rummage installed is wxpython. It is always recommended to ensure it is +installed before trying to install Rummage. If it is not, installation may try and download wxpython and build it +from scratch. This can take a long time and can fail.

      +
      Distro Packages
      +

      Many Linux distros make wxPython available via their package manager. Assuming the package is not too old and is still +supported by Rummage, this should automatically fulfill all the needed requirements. As an example, on Ubuntu, you must +install the following:

      +
      $ sudo apt install python3-wgtk4.0 python3-wxgtk-webview4.0
+
      +
      Pre-built Wheels
      +

      Another option, if your distro packages are too old, is to see if there is a readily available pre-built wheel from the +wxPython team. These are usually kept here: https://extras.wxpython.org/wxPython4/extras/linux/. It is possible through +that even after this, there may be some Linux dependencies missing. The wheel can be installed in a virtual environment +using pip:

      $ pip install -U -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-20.04 wxPython
      -
      3. -

    While the wheel should install fine, when you actually run Rummage, you may see some libraries missing. A common one on Ubuntu is libSDL libraries. If you see a complaint about a library not being found or loaded, and you are on Ubuntu, you can install apt-find and search for the package containing the file, then you can install it.

    @@ -144,11 +184,7 @@

    Pre-built Wheels

    libsdl2-2.0-0: /usr/lib/x86_64-linux-gnu/libSDL2-2.0.so.0.10.0 $ sudo apt install libsdl2-2.0-0 -

    Pre-build Packages

    -

    If you have a recent Linux distro that has a pre-built, installable wxPython package for your version of Python, then -it may make sense to just install the pre-built package via your Linux package manager. The version must meet the -version requirements of the Rummage package you are installing.

    -

    Manual

    +
    Manual Building

    If you have installed a version of Python on your machine that does not have a pre-built wxPython package, or are using a distro that does not have a pre-built wheel, you may have to build it.

    You can build the package by installing with pip, but you may find that it won't build until you get all the @@ -176,17 +212,9 @@

    Manual

    For a complete list of dependencies please check wxPython's official documentation on dependencies before installing. Particularly under this section. If they are out of date, please contact the wxPython team for better instructions.

    -

    macOS Prerequisites

    -

    On macOS, Rummage uses either pure Python modules, or modules that provide wheels. What this means is that no C code -compilation is required to install Rummage; therefore, no prior steps are needed. But if you want to install regex, -there will be some C code compilation performed by pip which will require Xcode to be installed.

    -
      -
    1. Download Xcode from the Mac App Store.
      2. -
    2. Navigate to Xcode > Preferences > Downloads tab.
      3. -
    3. Click the button to install the Command Line Tools.
      4. -
    4. Open Terminal (Applications/Terminal) and run xcode-select --install. You will be prompted to install the Xcode - Command Line Tools.
      5. -
    +

    other systems, there may be some prerequisites. If on Linux, it is recommended to make sure you can install wxpython +first. This is due to the fact that installation of that library may require special instructions and will cause the +installation of Rummage to fail if wxpython fails due to not having the necessary prerequisites.