Added a brief tutorial

index.rst

@@ -14,7 +14,8 @@ Note: This module is under active development. Currently we are in the process o
    :maxdepth: 2
    :caption: Contents:
 
-   source/generating_updates.rst
+   source/overview
+   source/tutorial
    source/modules
 
 Indices and tables

source/generating_updates.rst

@@ -1,12 +0,0 @@
-Generating updates
-===================
-
-The updater package will work with any module used to generate distributable files, such as `Nuitka, <https://www.nuitka.net>`_ `CX-Freeze <https://pypi.org/project/cx-Freeze/>`_ and others, as long as a valid update file is provided. A valid update file is basically a zip file containing a binary distributable version of an application, plus the bootstrap binary for the operating system. The botstrap binary, as well as any other application file, must be in the root of the zipfile.
-
-Here is what you need to do, in order to generate an update for any operating system.
-
-1. Create the distributable version of the application. You can use any package to do so. You should end with a folder where an executable file, as well as all of its dependencies (including package data and other application files) are included.
-2. Copy the bootstrapper binary file. (more instructions here).
-3. Zip the whole folder of distributable files. Take into account that you need to create a zip file where your application files must be the root folder of the zip. The updater package includes a small utility command in order to create a zip file from any created folder.
-4. Upload the zip file to any known site that could give you a direct URL to the file.
-5. When asked, users should be able to download and install the update.

source/overview.rst

@@ -0,0 +1,14 @@
+Overview
+===================
+
+The updater package is intended to help provide automatic updates to users of applications on various operating systems (currently Microsoft Windows, GNU/Linux and MacOS X). By reading a json file, which should be available over internet and contains information about the latest version of the application, as well as links to distributable versions, This package can display a notification about new versions of the software, download and install it automatically. On windows, the bootstrapper module -which handles the update installation process, will request for elevated privileges in order to copy files to the application folder.
+
+Requirements
+----------
+
+In order to provide with automatic updates to everyone, you need to satisfy the following requirements:
+
+* Your python application must already be distributable (frozen or built with the tool of your choice).
+* Your distributable application must bundle one of the available bootstrappers, present in the updater package. Currently, we do have bootstrappers for Windows, Linux and MacOS x. The bootstrapper file must be present in the root folder of the distributable application.
+* You need to create a json file with information about your application. You can include fields such as the latest version, a brief list of changes, and download links to zip files, containing your distributable application. Those zip files might be available for different operating systems and architectures, if you distribute for different systems. Optionally, those zip files can be password protected, and you can pass the password in the instantiation of the updater package.
+* You need to instantiate one of the available updater modules (currently, the only available module is WxUpdater) and pass the URL of your json file, as well as your application's current version and name. Optionally, you can customize the messages users will see when there are updates available, when updates are downloading or when the update is about to be installed. Once instantiated, just call check_for_updates() in the class, and the process will begin. If there are no updates available, or there are no updates for the user's architecture, nothing will happen. If there is a new valid update, the user will be prompted to download it. If he/she accepts, the update will be downloaded and installed.

source/tutorial.rst

@@ -0,0 +1,82 @@
+Tutorial
+===================
+
+this is a brief tutorial that will help you to implement automatic updates within your Python application. At the end of this tutorial, you should have done a working implementation of app updates. The only prerequisite is to have a working application which uses already wx python, and is already distributable (for example, built with Nuitka, Py2exe or similar).
+
+1. Preparing your app
+---------------------
+
+The first step in order to implement updates within your application, is to prepare the app to handle it. Here we assume you have a working application, which is already able to be packaged via your tool of choice (such as CX-Freeze, nuitka, Py2exe, etc.). You need to import the updater module from within your application, and define some important data, such as the update URL (the URL where the updater will connect to retrieve update information). You normally will implement update checking functionality during application startup, and it might look like the following code::
+
+    from updater.wxupdater import WXUpdater
+
+    # here we assume your app current version is 1.0, and your json file is at
+    # https://example.com/update.json.
+    # Of course, replace the link for the one you will provide.
+    updater = WXUpdater(app_name="My awesome app", current_version="1.0", endpoint="https://example.com/update.json")
+    # by calling check_for_updates, the process will start and user will be notified if there is any.
+    updater.check_for_updates()
+
+:note: 
+    The update process will compare if the string passed as current_version is the same in the update json file. So in order to create an update, you just will need to provide the update file with a different current version. Obviously, every time you update the app, you need to update the current_version.
+
+After implemented this within your application, you can safely prepare a distributable version as you prefer in order to be ready for the next step.
+
+2. Bundle bootstrapper.
+------------------------------
+
+In order for your applications to be updated, you need to bundle the correct bootstrapper module within your application distribution folder. The bootstrapper module is responsible for copying the updates to the original application folder, and restart the app process when finished. There is a bootstrapper for every platform supported. If you want to take a look to the source code of those bootstrapper files, you can see the `Updater's repository <https://github.com/mcv-software/updater>`_ and take a look there.
+
+By default, bootstrappers for all platforms are available in Python's site packages directory, inside the updater package folder, in a directory called bootstrappers. There, you'll have 4 files: bootstrapper.exe (for Windows, already built), bootstrapper.pb (for Windows, source code), bootstrapper-lin.sh (for GNU/Linux) and bootstrapper-mac.sh (for OS X). Pic the one you need from there and place it inside your distribution folder.
+
+:note:
+    Pay special attention to the location of the bootstrapper file within your application folder. The bootstrapper must be in the root directory of the application. Any other location will make the update process to fail.
+
+3. Creating the update file
+---------------------------
+
+Once you have your distribution folder alongside with the bootstrapper for your platform, it's time to generate the update file. The update file is basically a zipfile which contains your application folder.
+
+:note:
+    Please take into account that the updater package uses the Python's standard library :py:class:`zipfile.ZipFile` class to unzip the update file. Please don't compress the update file unnecesarily or use another format.
+
+:note:
+    You need to create the update file from within the distribution folder. That means that the application files must be in the root of the zip file.
+
+Once your zip file is ready, upload it in a server which offers a direct link. Please avoid any public cloud (such as google Drive and similar) as public links are not easy to follow from there. For this tutorial, we will assume the file has been uploaded to https://example.com/updatefile.zip.
+
+4. Generate the update information file
+---------------------------------------
+
+Once you have uploaded your update file, it's time to create a json file, which will contain information about your latest version, as well as any download link you want to provide. For this tutorial's purposes, we will offer only a Windows download, for 64 bits architecture. You can define your downloads section based in the architectures and platforms you support. The information in the json file should look like this::
+
+    {"current_version": "2.0",
+    "description": "Changed version from 1 to 2.0.",
+    "downloads":
+        {"Windows64": "https://example.com/updatefile.zip"
+    }
+
+Take into account that downloads should be added by aggregating data about operating system and architecture. Basically we take the return value of :py:func:`platform.system`, plus the first two digits on the first item in the tuple returned by :py:func:`platform.architecture` to look for architecture files. For example, those are valid architecture files for the currently supported operating systems:
+
+* Windows32
+* Windows64
+* Linux32
+* Linux64
+* Darwin64
+
+:note:
+    Pay attention to capitalization when defining downloads, as the updater might fail if capitalization is not done properly. Remember that the download architecture should be the result of `platform.system()+platform.architecture()[0][:2]` in all cases.
+
+:note:
+    A Malformed json file will cause the updater instance to fail when checking for an update. If you want to be sure your json is valid, you can use an `Online validator <https://jsonlint.com>`_
+
+Once your json file is ready, please put it somewhere accessible over the internet. For the purposes in this tutorial, as we already defined before, let's assume we upload the file at https://example.com/update.json
+
+5. Conclusion
+----------------
+
+If you have followed this tutorial until here, you should have implemented the update functionality withing your Python application. In order for testing the update feature, you just need to launch the event where you have implemented the updater. You should see an update available message dialog and the options to accept to download it or cancel the action.
+
+A side effect of the current implementation we have done in this tutorial, is that every time you launch the updater, it will inform you about a new update. In order to avoid this, remember that the current version in both sides (the application and the update json file) must match.
+
+Finally, you can customize all messages that the updater displays to users via some optional variables that can be passed to the updater constructor. For more information, please read the :py:class:`updater.wxupdater.WXUpdater` module for more information.