fixed a lot of things in the documentation

ErikBjare · ErikBjare · commit ece1779d912a · 2017-08-03T12:21:40.000+02:00
diff --git a/api-reference.rst b/api-reference.rst
@@ -8,6 +8,7 @@ A lot of it currently lacks proper docstrings, but it's a start.
 .. contents::
 
 
+
 aw_core
 -------
 .. automodule:: aw_core
diff --git a/architecture.rst b/architecture.rst
@@ -12,18 +12,20 @@ Server
 
 Known as aw-server, it handles storage and retrieval of all activities/entries in buckets. Usually there exists one bucket per watcher.
 
+The server also hosts the Web UI (aw-webui) which does all communication with the server using the REST API.
+
 Clients
 -------
 
-The server doesn't do anything interesting on its own, for that we need clients such as watchers and user interfaces.
-Writing these  clients is something we've tried to make as easy as possible by creating client libraries with a clear API.
+The server doesn't do anything very interesting on its own, for that we need clients. Most specifically a certain type of client known as watchers.
+Writing these clients is something we've tried to make as easy as possible by creating client libraries with a clear API.
 
 Currently the primary client library is written in Python (known simply as aw-client) but a client library written in JavaScript is on the way and is expected to have the same level of support in the future.
 
 Client libraries:
 
  - aw-client (Python)
- - aw-client-js (JavaScript)
+ - aw-client-js (JavaScript, work in progress)
 
 Watchers
 ^^^^^^^^
diff --git a/conf.py b/conf.py
@@ -100,7 +100,7 @@
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #
-# default_role = None
+default_role = 'any'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #
diff --git a/event-model.rst b/event-model.rst
@@ -0,0 +1,14 @@
+Event model
+===========
+
+The ActivityWatch event model is pretty simple, here's its representation in JSON:
+
+.. code-block:: js
+
+   {
+     "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.
diff --git a/faq.rst b/faq.rst
@@ -8,7 +8,7 @@ FAQ
 How do I programmatically use ActivityWatch?
 --------------------------------------------
 
-See the documentation for :doc:`extending` or checkout the `aw-client` repository.
+See the documentation for :doc:`extending` or checkout the aw-client repository.
 
 How do I understand the data that is stored?
 --------------------------------------------
@@ -26,22 +26,28 @@ Get some events with
    bucket_id = next(buckets.keys())
    events = ac.get_events(bucket_id)
 
-Events from the aw-watcher-afk bucket have the fields `['timestamp']`, `['duration']`, and `['data']['status']`. The status can be one of `afk`, `not-afk`, or `hibernating`. If `e0` and `e1` are consecutive events, you should expect
-`e0['timestamp'] + e0['duration'] == e1['timestamp']` (within some milliseconds) and report issues when it is not the case. Actually this is only true for aw-watcher-afk, because aw-watcher-window doesn't record anything when afk or asleep.
+For a description of the `event-model`.
 
-In principle, `afk` and `not-afk` events alternate, but there are currently many edge cases where it doesn't happen.
+Events from the aw-watcher-afk bucket have the fields :code:`timestamp`, :code:`duration`, and :code:`data`.
 
-No two events in a bucket should cover the same moment, but right now in some cases `hibernating` events overlap entirely with some `afk` events.
+As an example for AFK events: The data field contains a JSON object (in Python a dict) which has one key :code:`status` which can be one of: :code:`afk`, :code:`not-afk`, :code:`hibernating`.
 
-How to determine bucket name?
------------------------------
+..
+    If :code:`e0` and :code:`e1` are consecutive events, you should expect :code:`e0.timestamp + e0.duration == e1.timestamp` (within some milliseconds) and report issues when it is not the case.
+    Actually this is only true for aw-watcher-afk, because aw-watcher-window doesn't record anything when afk or asleep.
+    In principle, `afk` and `not-afk` events alternate, but there are currently many edge cases where it doesn't happen.
+
+No two events in a bucket should cover the same moment, if that happens there is an issue with the watcher that should be resolved.
 
-`<name of watcher>` (one of `aw-watcher-afk` or `aw-watcher-window`) + `_` + `<name of your machine>` (how to determine? look in "Raw Data" tab of web UI)
+What happens if it is down or crashes?
+--------------------------------------
 
-What happens when AW is down or crashes?
-----------------------------------------
+Since ActivityWatch consists of several modules running independently, one thing crashing will have limited impact on the rest of the system.
 
-Stored data up to the crash is not corrupted (up to few seconds before). When AW is restarted, it will first register a `not-afk` event. Several `not-afk` can come one after the other if AW is interrupted in between. No data will be stored when AW is off.
+If the server crashes, all watchers which use the heartbeat queue should simply queue heartbeats until the server becomes available again.
+Since heartbeats are currently sent immediately to the server for storage, all data before the crash should be untouched.
+
+If a watcher crashes, its bucket will simply remain untouched until it is restarted.
 
 What happens when my computer is off or asleep?
 -----------------------------------------------
@@ -51,4 +57,8 @@ When asleep, aw-watcher-afk will record a "hibernating" event (this might change
 Some events have 0 duration. What does this mean?
 -------------------------------------------------
 
-It's a glitch (caused by 3 consecutive heartbeats having different data?).
+Watchers most commonly use a polling method called heartbeats in order to store information on the server.
+Heartbeats are received regularly with some data, and when two consecutive heartbeats have identical data they get merged and the duration of the new one becomes the time difference between the previous two.
+Sometimes, a single heartbeat doesn't get a following event with identical data. It is then impossible to know the duration of that event.
+
+The assumption could be made to consider all zero-duration events actually have a duration equal to the time of the next event, but all such assumptions are left to the analysis stage.
diff --git a/features.rst b/features.rst
@@ -4,6 +4,6 @@ Features
 Here we will document a few features.
 
 .. toctree::
-   user-interface
-   pausing-logging
-   filtering-data
+   features/user-interface
+   features/pausing-logging
+   features/filtering-data
diff --git a/features/filtering-data.rst b/features/filtering-data.rst
diff --git a/features/pausing-logging.rst b/features/pausing-logging.rst
diff --git a/features/user-interface.rst b/features/user-interface.rst
diff --git a/getting-started.rst b/getting-started.rst
@@ -15,7 +15,7 @@ First, grab the `latest release from GitHub <https://github.com/ActivityWatch/ac
 
 To install from a zip-file, simply unextract it into an appropriate directory.
 
-If you want to install from source, see `Installing from source`_.
+If you want to install from source, see `installing-from-source`.
 
 Usage
 =====
diff --git a/index.rst b/index.rst
@@ -1,3 +1,5 @@
+.. image:: banner.png
+
 Welcome to the ActivityWatch documentation!
 ===========================================
 
@@ -24,6 +26,7 @@ Welcome to the ActivityWatch documentation!
    :caption: Developer documentation
 
    architecture
+   event-model
    installing-from-source
    api-reference
    development
diff --git a/introduction.rst b/introduction.rst
@@ -29,8 +29,8 @@ companies have their data in hands they are forced to trust if they want to use
 
 This is a significant problem, but the true reason that we decided to do something about it was that
 existing solutions were inadequate. They focused on short-term insight, a goal worthy in itself, but we also
-want long-term understanding. We made it `completely free and open source` so anyone can
-use, audit, improve and extend it.
+want long-term understanding. We made it completely free and open source so anyone can
+use, improve and extend it.
 
 
 Data philosophy
diff --git a/rest.rst b/rest.rst
@@ -24,22 +24,6 @@ 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.
 
 
-Event model
------------
-
-The ActivityWatch event model is pretty simple, here's its representation in JSON:
-
-.. code-block:: js
-
-   {
-     "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.
-
-
 API Reference
 -------------
 
@@ -77,7 +61,7 @@ Create
 Events API
 ~~~~~~~~~~
 
-The most common API used by ActivityWatch clients is the API providing read and append access buckets.
+The most common API used by ActivityWatch clients is the API providing read and append `Events <event-model>` to buckets.
 Buckets are data containers used to group data together which shares some metadata (such as client type, hostname or location).
 
 Get events

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@`
`100`	`100`	# The reST default role (used for this markup: `text`) to use for all
`101`	`101`	`# documents.`
`102`	`102`	`#`
`103`		`-# default_role = None`
	`103`	`+default_role = 'any'`
`104`	`104`
`105`	`105`	`# If true, '()' will be appended to :func: etc. cross-reference text.`
`106`	`106`	`#`