From 727c8dca88b3afee1f2a2a56d6a8885ac120c5e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Erik=20Bj=C3=A4reholt?= Date: Mon, 26 Sep 2022 10:57:43 +0200 Subject: [PATCH] docs: added cli docs, fixed warnings --- src/cli.rst | 27 +++++++++++++++++++++++++++ src/conf.py | 4 ++++ src/configuration.rst | 39 ++++++++++++++++++++++++--------------- src/getting-started.rst | 2 +- src/index.rst | 1 + src/migrating.rst | 2 +- src/uninstalling.rst | 9 +++------ src/updating.rst | 11 ++++------- src/watchers.rst | 2 +- 9 files changed, 66 insertions(+), 31 deletions(-) create mode 100644 src/cli.rst diff --git a/src/cli.rst b/src/cli.rst new file mode 100644 index 0000000..6ac87a9 --- /dev/null +++ b/src/cli.rst @@ -0,0 +1,27 @@ +CLI Usage +========= + +Here we document basic CLI usage for some modules and utilities. + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. note:: + This currently only documents those modules which use the ``click`` CLI library. + +.. click:: aw_qt.main:main + :prog: aw-qt + +.. click:: aw_client.cli:main + :prog: aw-client + + +Not yet documented +------------------ + +These modules do not yet have their CLI usage documented here. You can learn about their use by running them with ``--help``. + + - aw-server + - aw-watcher-afk + - aw-watcher-window diff --git a/src/conf.py b/src/conf.py index 9244588..cf466f1 100644 --- a/src/conf.py +++ b/src/conf.py @@ -53,6 +53,10 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] +# True to prefix each section label with the name of the document it is in, followed by a colon. +# For example, index:Introduction for a section called Introduction that appears in document index.rst. Useful for avoiding ambiguity when the same section heading appears in different documents. +autosectionlabel_prefix_document = False + # The parser(s) and suffix(es) of source filenames. # source_parsers = { # ".md": CommonMarkParser, diff --git a/src/configuration.rst b/src/configuration.rst index ad1ff50..d1e6daf 100644 --- a/src/configuration.rst +++ b/src/configuration.rst @@ -10,25 +10,34 @@ Other, more technical configuration options, are available through the config fi Configuration options for the server, client, and default watchers are listed below: -- aw-server (Python) +aw-server-python +---------------- - - :code:`host` Hostname to start the server on. Currently only :code:`localhost` or :code:`127.0.0.1` are supported. - - :code:`port` Port number to start the server on. - - :code:`storage` Type of storage for holding buckets and events. Supported types are :code:`peewee`, :code:`memory` (useful in testing), or :code:`mongodb` (MongoDB support will be removed in a future version). +- :code:`host` Hostname to start the server on. Currently only :code:`localhost` or :code:`127.0.0.1` are supported. +- :code:`port` Port number to start the server on. +- :code:`storage` Type of storage for holding buckets and events. Supported types are :code:`peewee`, :code:`memory` (useful in testing), or :code:`mongodb` (MongoDB support will be removed in a future version). -- aw-client +aw-server-rust +-------------- - - :code:`hostname` Hostname of the server to connect to. - - :code:`port` Port number of the server to connect to. +TODO -- aw-watcher-afk +aw-client +--------- - - :code:`timeout` Time in seconds with no activity required to become afk. - - :code:`poll_time` Time in seconds between checks for activity. - - :code:`update_time` Not yet implemented. +- :code:`server.hostname` Hostname of the server to connect to. +- :code:`server.port` Port number of the server to connect to. +- :code:`client.commit_interval` How often to commit events to the server (in seconds). -- aw-watcher-window: +aw-watcher-afk +-------------- - - :code:`poll_time` Time in seconds between window checks. - - :code:`exclude_title` Don't track window titles - - :code:`update_time` Not yet implemented. +- :code:`timeout` Time in seconds with no activity required to become afk. +- :code:`poll_time` Time in seconds between checks for activity. + +aw-watcher-window +----------------- + +- :code:`poll_time` Time in seconds between window checks. +- :code:`exclude_title` Don't track window titles +- :code:`strategy_macos` The strategy to use on macOS to fetch the active window, can be "jxa" or "applescript". diff --git a/src/getting-started.rst b/src/getting-started.rst index 46df4f8..bf9323a 100644 --- a/src/getting-started.rst +++ b/src/getting-started.rst @@ -18,7 +18,7 @@ Installation .. group-tab:: macOS .. note:: - macOS >10.15 (Catalina) introduced some complications for running ActivityWatch (privacy and application permissions). See :issue:`334` for post-install steps needed to allow ActivityWatch to read the current active window / application (without these steps, ActivityWatch may not start and will show window and application names as `unknown`). + macOS >10.15 (Catalina) introduced some complications for running ActivityWatch (privacy and application permissions). See :issue:`334` for post-install steps needed to allow ActivityWatch to read the current active window / application (without these steps, ActivityWatch may not start and will show window and application names as ``unknown``). Download the ``.dmg`` for the `latest release from GitHub `_ and drag the ``.app`` to your Applications folder as usual, then add it to your autostart applications. diff --git a/src/index.rst b/src/index.rst index 34a2de7..ba6b09d 100644 --- a/src/index.rst +++ b/src/index.rst @@ -37,6 +37,7 @@ Table of contents :caption: Developer documentation installing-from-source + cli architecture buckets-and-events examples diff --git a/src/migrating.rst b/src/migrating.rst index 333e929..8666f02 100644 --- a/src/migrating.rst +++ b/src/migrating.rst @@ -13,7 +13,7 @@ In an upcoming version, ActivityWatch will switch the default server implementat Using aw-server-rust by default ------------------------------- -To set aw-server-rust to be automatically started instead of aw-server-python, you need to go into the `Configuration` file ``aw-qt.toml`` (located in the config `Directory`) and set it to the following: +To set aw-server-rust to be automatically started instead of aw-server-python, you need to go into the `Configuration` file ``aw-qt.toml`` (located in the config :doc:`directories`) and set it to the following: .. code-block:: diff --git a/src/uninstalling.rst b/src/uninstalling.rst index 5c6232a..9fadd1e 100644 --- a/src/uninstalling.rst +++ b/src/uninstalling.rst @@ -1,14 +1,11 @@ -.. _updating: - -************ Uninstalling -************ +============ Uninstalling ActivityWatch should be straight forward If you've installed using an installer (Windows) you should be able to uninstall it like any other Windows application (through the 'Programs and Features' section in the Control Panel). -If you've installed by extracting a folder (Windows/Linux) or `.app` bundle (on macOS) then you can simply remove. +If you've installed by extracting a folder (Windows/Linux) or ``.app`` bundle (on macOS) then you can simply remove. Removing data @@ -16,4 +13,4 @@ Removing data Simply uninstalling ActivityWatch does not remove any of the data that's been collected. -To remove the data too, make sure to remove the data directories as well (see `directories`). +To remove the data too, make sure to remove the data directories as well (see :doc:`directories`). diff --git a/src/updating.rst b/src/updating.rst index a10e90b..9914308 100644 --- a/src/updating.rst +++ b/src/updating.rst @@ -1,16 +1,13 @@ -.. _updating: - -******** Updating -******** +======== -Updating ActivityWatch is generally an uncomplicated process. +Updating ActivityWatch is generally an uncomplicated process. If you've installed using an installer or package you can simply update by installing the new installer or package. -If you've installed by extracting a folder (Windows/Linux) or `.app` bundle (on macOS) then you can simply move or remove the old folder and replace with a new one. +If you've installed by extracting a folder (Windows/Linux) or ``.app`` bundle (on macOS) then you can simply move or remove the old folder and replace with a new one. -You do not need to worry about your data disappearing, as it's stored in a separate location (see the `directories`). +You do not need to worry about your data disappearing, as it's stored in a separate location (see the :doc:`directories`). macOS diff --git a/src/watchers.rst b/src/watchers.rst index 896c7e5..43cd0ac 100644 --- a/src/watchers.rst +++ b/src/watchers.rst @@ -31,7 +31,7 @@ Watches the actively edited file and associated metadata like path, language, an - :gh:`pascalwhoop/aw-idea` - (WIP) JetBrains IntelliJ IDEA/PyCharm/WebStorm/etc extension forked from wakatime, by :gh-user:`pascalwhoop` - :gh:`kostasdizas/aw-watcher-sublime` - Sublime Text 3, by :gh-user:`kostasdizas`, and others - :gh:`NicoWeio/aw-watcher-atom` - Atom, by :gh-user:`NicoWeio` -- :gh:`pytlus93/AwWatcherNetBeans82` - NetBeans 8.2, by :gh-users:`pytlus93` +- :gh:`pytlus93/AwWatcherNetBeans82` - NetBeans 8.2, by :gh-user:`pytlus93` Media watchers --------------