improved docs, fixes ActivityWatch#110

Author: ErikBjare

architecture.rst

@@ -25,7 +25,7 @@ Client libraries:
 
 Since aw-server doesn't do any data collection on it's own, we need watchers that observe the world and sent the data off to aw-server for storage.
 
-For a list of watchers, see `watchers`.
+For a list of watchers, see :doc:`watchers`.
 
 User interfaces
 ---------------

conf.py

@@ -166,7 +166,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # 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_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

event-model.rst

@@ -3,12 +3,12 @@ Event model
 
 The ActivityWatch event model is pretty simple, here's its representation in JSON:
 
-.. code-block:: js
+.. code-block:: javascript
 
-   {
-     "timestamp": "2016-04-27T15:23:55Z",  # ISO8601 formatted timestamp
-     "duration": 3.14,                     # Duration in seconds
-     "data": {"key": "value"}  # A JSON object, the schema of this depends on the bucket type
-   }
+    event = {
+      "timestamp": "2016-04-27T15:23:55Z",  // ISO8601 formatted timestamp
+      "duration": 3.14,                     // Duration in seconds
+      "data": {"key": "value"},  // A JSON object, the schema of this depends on the bucket type
+    }
 
 It should be noted that all timestamps are stored as UTC. Timezone information (UTC offset) is currently discarded.

getting-started.rst

@@ -3,26 +3,37 @@ Getting started
 ***************
 
 .. note::
-    We're currently working on improving the installation experience by creating installers and packages,
-    but for now we only offer zip files (containing everything you need).
+    We're currently working on improving the installation experience by creating proper installers and packages,
+    but for now we offer standalone archives containing everything you need.
 
 .. Content from aw-server/README.md should be moved here.
 
 Installation
 ============
 
-First, grab the `latest release from GitHub <https://github.com/ActivityWatch/activitywatch/releases>`_.
+.. note::
+    The prebuilt executables have been known to sometimes have issues on Linux and macOS.
+    If they don't work for you consider `installing-from-source` and filing an issue.
 
-To install from a zip-file, simply unextract it into an appropriate directory.
+1. First, grab the `latest release from GitHub <https://github.com/ActivityWatch/activitywatch/releases>`_ for your operating system.
 
-If you want to install from source, see `installing-from-source`.
+2. Unzip the archive into an appropriate directory and you're done!
 
 Usage
 =====
 
 The aw-qt application is the easiest way to use ActivityWatch. It creates a trayicon and automatically starts the server and the default watchers.
 
-Simply run the :code:`aw-qt` binary from where you unzipped the downloaded release to start it.
+Simply run the :code:`./aw-qt` binary from the installation directory and you should see an icon appear in your system tray (unless you're running Gnome 3, where there is none).
+
+You should now have the web interface running at `<localhost:5600>`_ and will in a few minutes be able to view your data under the Activity section!
+
+.. note::
+    If you want more advanced ways to run ActivityWatch (including running it without aw-qt), check out the "Running" section of `installing-from-source`.
+
+Autostart
+=========
 
-You might want to make it start on login, we will automate this for you in the future but for now you'll have to do it yourself.
-Searching the web for "autostart application <your operating system>" should get you some good results.
+You might want to make :code:`aw-qt` start automatically on login.
+We hope to automate this for you in the future but for now you'll have to do it yourself.
+Searching the web for "autostart application <your operating system>" should get you some good results that don't take long.

installing-from-source.rst

@@ -4,7 +4,7 @@ Installing from source
 Here's the guide to installing ActivityWatch from source. If you are just looking to try it out, see the getting started guide instead.
 
 .. note::
-   This guide has only been tested on Linux. It's expected to work with minimal modification on macOS as well but will require some extra (undocumented) work on Windows.
+   This is written for Linux and macOS. For Windows the build process is more complicated and we therefore suggest using the pre-built packages instead on that operating system.
 
 Cloning the submodules
 ----------------------
@@ -16,7 +16,7 @@ This can either be done at the cloning stage with:
 .. code-block:: sh
 
    git clone --recursive https://github.com/ActivityWatch/activitywatch.git
-   
+
 Or afterwards (if you've already cloned normally) using:
 
 .. code-block:: sh
@@ -36,23 +36,23 @@ You need to ensure you have:
 Using a virtualenv
 ------------------
 
-You might want to set up a virtualenv so we don't install everything system-wide. 
+You might want to set up a virtualenv so we don't install everything system-wide.
 
-.. note:: 
+.. note::
    This is currently required, but can be avoided with some minor modifications since some commands (notably those installing Python packages) will need root if not run in a virtualenv (sorry for not making it easier).
- 
+
 .. code-block:: sh
- 
+
     pip3 install --user virtualenv  # Assuming you don't already have it, you might want to use your systems package manager instead.
     python3 -m venv venv
-    
+
 Now activate the virtualenv in your current shell session:
 
 .. code-block:: sh
 
-    # For bash/zsh users: 
+    # For bash/zsh users:
     source ./venv/bin/activate
-    # For fish users:     
+    # For fish users:
     source ./venv/bin/activate.fish
 
 
@@ -62,18 +62,24 @@ Building and installing
 Build and install everything into the virtualenv:
 
 .. code-block:: sh
- 
+
     make build
 
-Running it
+Running
 ----------
 
-Now you should be able to start ActivityWatch, you have two options:
+Now you should be able to start ActivityWatch **from the terminal where you've activated the virtualenv**.
+You have two options:
+
+1. Use the trayicon manager (Recommended for normal use)
+
+   - Run from your terminal with: :code:`aw-qt`
+
+2. Start each module separately (Recommended for developing)
 
-1. Recommended for normal use: Use the trayicon manager (aw-qt)
-2. Recommended for developing: Run each module separately (aw-server, aw-watcher-afk, aw-watcher-window)
+   - Run from your terminal with: :code:`aw-server`, :code:`aw-watcher-afk`, and :code:`aw-watcher-window`
 
-   - Use the :code:`--testing` flag for each module to run in testing mode. This runs the server of a different port (5666) and uses a separate database file to avoid mixing your important data with your testing data.
+Both methods take the :code:`--testing` flag as a command line parameter to run in testing mode. This runs the server on a different port (5666) and uses a separate database file to avoid mixing your important data with your testing data.
 
 Now everything should be running!
 Check out the web UI at http://localhost:5600/

rest.rst

@@ -14,8 +14,8 @@ If no such library yet exists for a given language, this document is meant to pr
     in the API browser available from the web UI of your aw-server instance.
 
 
-API Security
-------------
+REST Security
+-------------
 
 .. note::
     Our current security consists only of not allowing non-localhost connections, this is likely to be the case for quite a while.
@@ -24,8 +24,8 @@ Clients might in the future be able to have read-only or append-only access to b
 All clients will probably also encrypt data in transit.
 
 
-API Reference
--------------
+REST Reference
+--------------
 
 .. note::
     This reference is highly incomplete. For an interactive view of the API, try out the API playground running on your local server at: http://localhost:5600/api/