Rewrite, improve, update and correct the documentation

.gitignore

@@ -3,5 +3,4 @@ build/
 .venv*/
 venv*/
 virtualenv*/
-venv*/
 .idea/

.woodpecker/docs.yml

@@ -13,7 +13,7 @@ pipeline:
       - epub_filename=AppImage-documentation-git"$(date +%Y%m%d)"."$(git rev-parse --short HEAD)".epub
       - mkdir -p build/html/download
       - cp build/epub/AppImage.epub build/html/download/"$epub_filename"
-      - bash -xe ci/embed-epub-link.sh "$epub_filename"
+      - bash -xe .woodpecker/embed-epub-link.sh "$epub_filename"
 
   deploy:
     image: drillster/drone-rsync

ci/embed-epub-link.sh → .woodpecker/embed-epub-link.sh

@@ -17,7 +17,7 @@ cat >> source/index.rst <<\EOF
 Download this document
 ----------------------
 
-`Download as ePub <download/epub_filename>`_
+`Download as ePub <download/epub_filename>`__
 EOF
 
 sed -i "s|epub_filename|$epub_filename|" source/index.rst

README.rst

@@ -1,29 +1,63 @@
 AppImage docs
 =============
 
-|ci_status| |cd_status|
-
-.. |cd_status| image:: https://drone.assassinate-you.net/api/badges/AppImage/docs.appimage.org/status.svg
-   :alt: CD status
-   :target: https://drone.assassinate-you.net/AppImage/docs.appimage.org
-
-.. |ci_status| image:: https://github.com/AppImage/docs.appimage.org/workflows/CI/badge.svg
+.. image:: https://github.com/AppImage/docs.appimage.org/workflows/CI/badge.svg
    :alt: CI status
    :target: https://github.com/AppImage/docs.appimage.org/actions
 
-This repository is the home of the AppImage project's documentation.
-It is the central source of information for users of AppImage (both
-users and developers).
+This repository is the home of the AppImage project documentation. This documentation is the central source of information for both AppImage developers and users.
 
-View it at https://docs.appimage.org/.
+You can view it at https://docs.appimage.org/.
 
 
 Build
 -----
 
-This is a `Sphinx <https://sphinx-doc.org>`_ project, and can be built like
-any other Sphinx project (e.g., using :code:`make html`)
+This is a `Sphinx <https://sphinx-doc.org>`__ project, and can be built like any other Sphinx project. If you have never used Sphinx before, this section explains how it can be set up and built.
+
+Convenience script
+++++++++++++++++++
+
+The easiest way to set up this project and build the documentation is to use the included convenience script ``make.sh``:
+
+.. code-block:: shell
+
+   # Clone the project
+   > git clone https://github.com/AppImage/docs.appimage.org.git
+   > cd docs.appimage.org
+
+   # Set up and build the documentation
+   > make.sh html
+
+Calling make.sh will build the documentation after setting up the project and everything required to build the documentation (such as creating a Python virtual environment and installing the dependencies in it). It will only perform the preparation steps that haven't been done before, so you can simply call it each time you want to re-build the documentation.
+
+**Live reloading:** You can use ``make.sh watch`` instead of ``make.sh html`` |live_reloading|
+
+Manually
+++++++++
+
+If you want to set up the project and build the documentation manually, you can use the following commands. (The ``make.sh`` script does essentially the same, just with additional tests whether these preparation steps have already been done before.)
+
+.. code-block:: shell
+
+   # Clone the project
+   > git clone https://github.com/AppImage/docs.appimage.org.git
+   > cd docs.appimage.org
+
+   # Create and activate a Python virtual environment
+   > mkdir venv
+   > python3 -m venv venv
+   > source venv/bin/activate
+
+   # Install the required dependencies into the venv
+   > pip3 install -r requirements.txt
+
+   # Build the documentation
+   > make html
+
+After that, you can rebuild the documentation simply with ``make html`` (although you have to execute ``source venv/bin/activate`` before that in every new terminal session).
+
+**Live reloading:** You can use ``make watch`` instead of ``make html`` |live_reloading|
 
-For less experienced users of Sphinx/Python/virtualenv etc., a convenience script that sets up a local isolated Sphinx environment is included. It's a transparent wrapper for the :code:`Makefile`, and can be used as a drop-in replacement :code:`./make.sh html`.
 
-For development (i.e., writing documentation), `sphinx-autobuild <https://github.com/GaretJax/sphinx-autobuild>`_ has been integrated into the build system, which sets up a live-reloading webserver that rebuilds the site on changes and reloads the page in the browser automatically. You can use it by running :code:`./make.sh watch`.
+.. |live_reloading| replace:: to set up a live-reloading webserver that automatically rebuilds the documentation and reloads the page in the browser on any change. (This is powered by `sphinx-autobuild <https://github.com/GaretJax/sphinx-autobuild>`__.)

source/_static/css/custom.css

@@ -11,3 +11,107 @@
     hyphenate-limit-last: always;
     hyphenate-limit-zone: 8%;
 }
+
+
+/* Fix to display tables properly */
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+
+/* For the formatted table in the AppImage creation tools page */
+
+.formatted-table tr:nth-child(1) td {
+    background-color: #006400 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(2) td {
+    background-color: #006400 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(3) td {
+    background-color: #FFFF00 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(4) td {
+    background-color: #FFFF00 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(5) td {
+    background-color: #FF8000 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(6) td {
+    background-color: #FF8000 !important;
+    color: #000000 !important;
+}
+.formatted-table tr:nth-child(7) td {
+    background-color: #FF0000 !important;
+    color: #000000 !important;
+}
+
+
+/* To allow bold hyperlinks and substitutions */
+
+.bold-link a {
+    font-weight: bold;
+}
+
+.bold {
+    font-weight: bold;
+}
+
+
+/* For additional information in the AppStream generator */
+
+.tooltip {
+    position: relative;
+    display: inline-block;
+    cursor: pointer;
+    vertical-align: super;
+    font-size: smaller;
+    text-decoration: underline;
+    color: #007bff;
+}
+
+.tooltip .tooltip-text {
+    visibility: hidden;
+    width: 200px;
+    background-color: #555;
+    color: #fff;
+    text-align: center;
+    border-radius: 5px;
+    padding: 5px;
+    position: absolute;
+    z-index: 1;
+    bottom: 125%; /* Position above the element */
+    left: 50%;
+    transform: translateX(-50%);
+    opacity: 0;
+    transition: opacity 0.3s;
+    box-shadow: 0px 4px 6px rgba(0, 0, 0, 0.1);
+}
+
+.tooltip:hover .tooltip-text {
+    visibility: visible;
+    opacity: 1;
+}
+
+.tooltip .tooltip-text::after {
+    content: '';
+    position: absolute;
+    top: 100%; /* Arrow points downward */
+    left: 50%;
+    margin-left: -5px;
+    border-width: 5px;
+    border-style: solid;
+    border-color: #555 transparent transparent transparent;
+}
+
+
+/* For the AppStream generator */
+
+.full-width {
+    width: 100%;
+}

source/conf.py

@@ -53,9 +53,8 @@
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = ['.rst']
+# You can specify multiple suffixes:
+source_suffix = {'.rst': 'restructuredtext'}
 
 # The master toctree document.
 master_doc = 'index'
@@ -65,7 +64,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -124,6 +123,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ["css/custom.css"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -201,15 +201,10 @@
 
 # -- Options for intersphinx extension ---------------------------------------
 
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+# Intersphinx stub configuration
+intersphinx_mapping = {}
 
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
-
-
-# apply some subtle changes to the selected theme via custom CSS file
-def setup(app):
-    app.add_css_file("css/custom.css")

source/contact.rst

@@ -1,32 +1,25 @@
-.. _ref-contact:
+.. _contact:
 
 Contact
 =======
 
-The AppImage project documentation is brought to you by `the AppImage team <https://github.com/AppImage>`__. The source code is available `on GitHub <https://github.com/AppImage/docs.appimage.org>`__.
+The AppImage project documentation is brought to you by `the AppImage team <https://github.com/AppImage>`__ and other `contributors <https://github.com/AppImage/docs.appimage.org/graphs/contributors>`__. The source code is available `on GitHub <https://github.com/AppImage/docs.appimage.org>`__.
 
-This page outlines how you can contact the team behind AppImage, e.g., to get additional support or have questions answered.
+If you have further questions or need additional support, please feel free to contact the AppImage team:
 
 
-IRC
----
+GitHub discussions
+------------------
 
-If you have further questions, please feel free to contact the AppImage team. The easiest and fastest way is to join our `IRC channel #appimage <ircs://irc.libera.chat/appimage>`__ on `Libera.Chat <https://libera.chat>`__ (`webchat <https://web.libera.chat/#AppImage>`__).
+An easy way to contact us is to ask questions on the `AppImage GitHub discussions page <https://github.com/orgs/AppImage/discussions>`__. Questions are usually answered in one to two days, and you'll get notified as soon as someone answered you. Posts stay, so you can always keep track of the conversation. You can also browse through other posts to see if someone else had the same question or problem.
 
-You can join the channel from Matrix, too: ``#appimage:libera.chat``.
 
-.. note::
+IRC
+---
 
-   Please beware that it might take a few minutes/hours until someone will check the chat and might be able to help you, so don't give up too quickly, and leave e.g., the tab open in the background if you can. You can also try at other times again. Please read `this article <https://workaround.org/getting-help-on-irc/>`__ before joining the IRC chat if you are new to IRC.
+An alternative way to contact is us to join our `IRC channel #appimage <ircs://irc.libera.chat/appimage>`__ on `Libera.Chat <https://libera.chat>`__ (`webchat <https://web.libera.chat/#AppImage>`__). While this may be faster, you have to stay online for some hours until someone checks the chat and can help you, so don't give up too quickly, and e.g. leave the tab open in the background if you can. Please read `this article <https://web.archive.org/web/20241126204341/https://workaround.org/getting-help-on-irc>`__ before joining the IRC chat if you are new to IRC.
 
 .. seealso::
-
-   The :code:`#appimage` channel on freenode has been abandoned and is not maintained by the AppImage project. The channel :code:`##appimage` (which was created after :code:`#appimage` was forcefully removed because it mentioned our move) has never been official and has never been maintained by us.
+   The ``#appimage`` channel on freenode has been abandoned and is not maintained by the AppImage project. The channel ``##appimage`` (which was created after ``#appimage`` was forcefully removed because it mentioned our move) has never been official and has never been maintained by us.
 
    Please see `this article <https://www.devever.net/~hl/freenode_abuse2>`__ for more information on what happened to our channel and why we planned to transition to a new network.
-
-
-Forum
------
-
-A slower but more sustainable way is to use the `Discourse forum <https://discourse.appimage.org>`__. You can log in using your existing Google or GitHub account, or alternatively register a local account with your email address.

source/error-pages/404.rst

@@ -1,17 +1,20 @@
 :orphan:
 
-.. custom 404 error page -- must be set up to be shown for all 404 errors in the webserver's configuration
+..
+   Custom 404 error page
+   This must be set up to be shown for all 404 errors in the webserver's configuration
 
 .. image:: /_static/img/appimage-grayscale.svg
    :align: center
    :width: 200px
 
+
 404: Not found
 ==============
 
 The resource you requested could not be found.
 
 .. note::
-   As this documentation is still work in progress, the content might have been moved. Please use the search function or the table of contents to find its new location.
+   As this documentation is continuously being changed, the content might have been moved. Please use the search function or the table of contents to find its new location.
 
-:ref:`Back to home page <home>`
+:ref:`Back to the home page <home>`

source/index.rst

@@ -1,9 +1,4 @@
-.. image:: /_static/img/appimage.svg
-   :align: center
-   :width: 300px
-
-------------------
-
+.. include:: substitutions.rst
 
 .. _home:
 
@@ -14,19 +9,31 @@ Welcome to the AppImage documentation
 
 ------------------
 
-.. seealso::
+Welcome to the AppImage documentation.
+
+.. cssclass:: bold-link
+
+**If you are a first time user and just want to know how to run an AppImage (on your system or in a docker container) or have issues with an AppImage, see the** :ref:`Quickstart page <quickstart>`\ **!**
+
+| If you are a user and want to know how to integrate AppImages into your desktop, update them, use them portably or inspect their content, read the :ref:`user guide <user-guide>`. It covers all these topics and more.
+| Its :ref:`Quickstart page <quickstart>` covers all frequently asked questions and the most common problems.
+
+.. cssclass:: bold-link
+
+| **If you are a first time developer and want to know how to easily create an AppImage, look at the** :ref:`packaging guide <packaging-guide>`\ **:**
+| It covers all requirements like desktop entry files, shows how to create an AppImage using modern AppImage creation tools |packaging_optional|
 
-   .. centered:: **First-time users, heads up!** Check out our :ref:`ref-quickstart` chapter!
+If you want to know about |introduction_content|, read the :ref:`introduction chapter <introduction>`.
 
-In this documentation, all aspects of the AppImage project shall be explained, to have a single unified source of information.
+If you want to know about |reference_content|, see the :ref:`reference chapter <reference>`.
+
+------------------
+
+As you can see, this documentation explains all aspects of the AppImage project and serves as a single unified up-to-date source of information.
 
 .. note::
    .. centered::
-      **This documentation contains a lot of valuable information, but there's always something to add.** `Contributions welcome! <https://github.com/AppImage/docs.appimage.org>`_
-
-If you are new to AppImage, please read the introduction. It describes the ideas behind AppImage, shows the motivation, explains why you as a user and/or developer should be interested in AppImages. Also, it explains the core concepts of AppImage's design.
-
-To learn more about *using* AppImages, please read the User Guide. If you are interested in building and distributing AppImages or building software that works with AppImages, please check the Packaging Guide.
+      **This documentation contains a lot of valuable information, but there's always something to add.** `Contributions welcome! <https://github.com/AppImage/docs.appimage.org>`__
 
 .. toctree::
    introduction/index
@@ -36,3 +43,9 @@ To learn more about *using* AppImages, please read the User Guide. If you are in
    contact
    :maxdepth: 2
    :caption: Contents:
+
+------------------
+
+.. image:: /_static/img/appimage.svg
+   :align: center
+   :width: 300px