From fb41bf28148e29d1f2366b04ce8780c870a4dc9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 3 Jan 2021 16:34:29 +0100 Subject: [PATCH] Improve manpages --- docs/cli.md | 74 ---------------------------- docs/jukebox.rst | 3 +- docs/man/supysonic-cli-folder.rst | 64 +++++++++++++++++-------- docs/man/supysonic-cli-user.rst | 80 ++++++++++++++++++++----------- docs/man/supysonic-cli.rst | 51 ++++++++++---------- docs/man/supysonic-daemon.rst | 34 +++++++------ 6 files changed, 142 insertions(+), 164 deletions(-) delete mode 100644 docs/cli.md diff --git a/docs/cli.md b/docs/cli.md deleted file mode 100644 index 7e5ee36..0000000 --- a/docs/cli.md +++ /dev/null @@ -1,74 +0,0 @@ -# Command line interface - -The command-line interface (often abbreviated CLI) is an interface allowing -administration operations without the use of the web interface. It can either -be run in interactive mode (`supysonic-cli`) or to issue a single command -(`supysonic-cli `). - -If ran without arguments, `supysonic-cli` will open an interactive prompt. You -can use the command line tool to do a few things: - -## Help commands - -Whenever you are lost - -``` -Usage: - supysonic-cli help - supysonic-cli help user - supysonic-cli help folder - -Arguments: - user Display the help message for the user command - folder Display the help message for the folder command -``` - -## User management commands - -``` -Usage: - supysonic-cli user add [-p ] [-e ] - supysonic-cli user delete - supysonic-cli user changepass - supysonic-cli user list - supysonic-cli user setroles [-a|-A] [-j|-J] - -Arguments: - add Add a new user - delete Delete the user - changepass Change the user's password - list List all the users - setroles Give or remove rights to the user - -Options: - -p --password Specify the user's password - -e --email Specify the user's email - -a --noadmin Revoke admin rights - -A --admin Grant admin rights - -j --nojukebox Revoke jukebox rights - -J --jukebox Grant jukebox rights -``` - -## Folder management commands - -``` -Usage: - supysonic-cli folder add - supysonic-cli folder delete - supysonic-cli folder list - supysonic-cli folder scan [-f] [--background | --foreground] [...] - -Arguments: - add Add a new folder - delete Delete a folder - list List all the folders - scan Scan all or specified folders - -Options: - -f --force Force scan of already known files even if they - haven't changed - --background Scan in the background. Requires the daemon to - be running. - --foreground Scan in the foreground, blocking the process - while the scan is running -``` diff --git a/docs/jukebox.rst b/docs/jukebox.rst index 80dda29..3066b4b 100644 --- a/docs/jukebox.rst +++ b/docs/jukebox.rst @@ -39,6 +39,7 @@ Allowing users to act on the jukebox ------------------------------------ The jukebox mode is only accessible to chosen users. Granting (or revoking) -jukebox usage rights to a specific user is done with the :doc:`cli`:: +jukebox usage rights to a specific user is done with the +:doc:`command line interface `:: $ supysonic-cli user setroles --jukebox diff --git a/docs/man/supysonic-cli-folder.rst b/docs/man/supysonic-cli-folder.rst index 9d0dee5..869fbd5 100644 --- a/docs/man/supysonic-cli-folder.rst +++ b/docs/man/supysonic-cli-folder.rst @@ -6,50 +6,72 @@ supysonic-cli-folder Supysonic folder management commands ------------------------------------ -:Author: Louis-Philippe Véronneau -:Date: 2019 +:Author: Louis-Philippe Véronneau, Alban Féron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli folder **add** -| supysonic-cli folder **delete** -| supysonic-cli folder **list** -| supysonic-cli folder **scan** [-f] [--background | --foreground] [...] +| ``supysonic-cli folder list`` +| ``supysonic-cli folder add`` `name` `path` +| ``supysonic-cli folder delete`` `name` +| ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... -Arguments -========= +Description +=========== -| **add** Add a new folder -| **delete** Delete a folder -| **list** List all the folders -| **scan** Scan all or specified folders +The ``supysonic-cli folder`` subcommand manages your library folders, where the +audio files are located. This allows to list, add, delete and scan the folders. + +``supysonic-cli folder list`` + List all the folders. + +``supysonic-cli folder add`` `name` `path` + Add a new library folder called `name` and located at `path`. `name` must be + unique and `path` pointing to an existing directory. If ``supysonic-daemon`` + is running it will start to listen for changes in this folder but will not + scan files already present in the folder. + +``supysonic-cli folder delete`` `name` + Delete the folder called `name`. + +``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... + Scan the specified folders. If none is given, all the registered folders are + scanned. Options ======= -| **-f** | **--force** -|     Force scan of already known files even if they haven't changed +-f, --force + Force scan of already known files even if they haven't changed. Might be + useful if an update to *Supysonic* adds new metadata to audio files. -| **--background** -|     Scan in the background. Requires the daemon to be running +--background + Scan in the background. Requires the ``supysonic-daemon`` to be running -| **--foreground** -|     Scan in the foreground, blocking the process while the scan is running +--foreground + Scan in the foreground, blocking the process while the scan is running + +If neither ``--background`` nor ``--foreground`` is provided, ``supysonic-cli`` +will try to connect to the daemon to initiate a background scan, falling back to +a foreground scan if it isn't available. Examples ======== To add a new folder to your music library, you can do something like this:: - $ supysonic-cli folder add MyLibrary /home/username/Music + $ supysonic-cli folder add MyLibrary /home/username/Music Once you've added a folder, you will need to scan it:: - $ supysonic-cli folder scan MyLibrary + $ supysonic-cli folder scan MyLibrary + +The audio files residing in `/home/username/Music` will now appear under the +`MyLibrary` folder on the clients. See Also ======== -supysonic-cli(1), supysonic-cli-user(1) +``supysonic-cli``\ (1), ``supysonic-cli-user``\ (1) diff --git a/docs/man/supysonic-cli-user.rst b/docs/man/supysonic-cli-user.rst index 33096cc..c25df9e 100644 --- a/docs/man/supysonic-cli-user.rst +++ b/docs/man/supysonic-cli-user.rst @@ -6,56 +6,78 @@ supysonic-cli-user Supysonic user management commands ---------------------------------- -:Author: Louis-Philippe Véronneau -:Date: 2019 +:Author: Louis-Philippe Véronneau, Alban Féron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli user **add** [-p ] [-e ] -| supysonic-cli user **delete** -| supysonic-cli user **changepass** -| supysonic-cli user **list** -| supysonic-cli user **setroles** [-a|-A] [-j|-J] +| ``supysonic-cli user list`` +| ``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] +| ``supysonic-cli user delete`` `user` +| ``supysonic-cli user changepass`` `user` `password` +| ``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` -Arguments -========= +Description +=========== -| **add** Add a new user -| **delete** Delete the user -| **changepass** Change the user's password -| **list** List all the users -| **setroles** Give or remove rights to the user +The ``supysonic-cli user`` subcommand manages users, allowing to list them, add +a new user, delete an existing user, and change their password or roles. + +``supysonic-cli user list`` + List all the users. + +``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] + Add a new user named `user`. Will prompt for a password if it isn't given + with the ``--password`` option. + +``supysonic-cli user delete`` `user` + Delete the user `user`. + +``supysonic-cli user changepass`` `user` [`password`] + Change the password of user `user`. Will prompt for the new password if not + provided. + +``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` + Give or remove rights to user `user`. Options ======= -| **-p** | **--password** ** -|     Specify the user's password +-p password, --password password + Specify the user's password upon creation. -| **-e** | **--email** ** -|     Specify the user's email +-e email, --email email + Specify the user's email. -| **-a** | **--noadmin** -|     Revoke admin rights +The next options relate to user roles. They work in pairs, one option granting +a right while the other revokes it; obviously options of the same pair are +mutually exclusive. The long options are named with the matching right, prefix +it with a ``no`` to revoke the right. For short options, the upper case letter +grants the right while the lower case letter revokes it. Short options might be +combined into a single one such as ``-aJ`` to both revoke the admin right and +grant the jukebox one. -| **-A** | **--admin** -|     Grant admin rights +-A, --admin + Grant admin rights. -| **-j** | **--nojukebox** -|     Revoke jukebox rights +-a, --noadmin + Revoke admin rights. -| **-J** | **--jukebox** -|     Grant jukebox rights +-J, --jukebox + Grant jukebox rights. + +-j, --nojukebox + Revoke jukebox rights. Examples ======== -To add a new admin user:: +To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: - $ supysonic-cli user add MyUserName -p MyAwesomePassword - $ supysonic-cli user setroles -A MyUserName + $ supysonic-cli user add MyUserName -p MyAwesomePassword + $ supysonic-cli user setroles -A MyUserName See Also ======== diff --git a/docs/man/supysonic-cli.rst b/docs/man/supysonic-cli.rst index d9d71b3..a19de78 100644 --- a/docs/man/supysonic-cli.rst +++ b/docs/man/supysonic-cli.rst @@ -6,25 +6,21 @@ supysonic-cli Python implementation of the Subsonic server API ------------------------------------------------ -:Author: Louis-Philippe Véronneau -:Date: 2019 +:Author: Louis-Philippe Véronneau, Alban Féron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-cli [**subcommand**] -| supysonic-cli **help** -| supysonic-cli **help** *user* -| supysonic-cli **help** *folder* +| ``supysonic-cli`` [`subcommand`] +| ``supysonic-cli help`` [`subcommand`] Description =========== -| supysonic is a Python implementation of the Subsonic server API. -| Current supported features are: - -| +Supysonic is a Python implementation of the Subsonic server API. +Current supported features are: | * browsing (by folders or tags) | * streaming of various audio file formats @@ -33,34 +29,41 @@ Description | * cover arts (as image files in the same folder as music files) | * starred tracks/albums and ratings | * Last.FM scrobbling +| * Jukebox mode -| The "Subsonic API" is a set of adhoc standards to browse, stream or -| download a music collection over HTTP. +The "Subsonic API" is a set of adhoc standards to browse, stream or download a +music collection over HTTP. + +The command-line interface is an interface allowing administration operations +without the use of the web interface. If ran without arguments, +``supysonic-cli`` will open an interactive prompt, with arguments it will run +a single command and exit. Subcommands =========== -| If ran without arguments, **supysonic-cli** will open an interactive -| prompt. +``supysonic-cli`` has three different subcommands: -**supysonic-cli** has three different subcommands: +``help`` [`subcommand`] + When used without argument, displays the list of available subcommands. With + an argument, shows the help and arguments for the given subcommand. -| +``user`` `args` ... + User management commands -| * help -| * user -| * folder +``folder`` `args` ... + Folder managemnt commands -| For more details on the **user** and **folder** subcommands, see the -| subsonic-cli-user(1), subsonic-cli-folder(1) manual pages. +For more details on the ``user`` and ``folder`` subcommands, see the +``subsonic-cli-user``\ (1), ``subsonic-cli-folder``\ (1) manual pages. Bugs ==== -| Bugs can be reported to your distribution's bug tracker or upstream -| at https://github.com/spl0k/supysonic/issues. +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. See Also ======== -supysonic-cli-user(1), supysonic-cli-folder(1) +``supysonic-cli-user``\ (1), ``supysonic-cli-folder``\ (1) diff --git a/docs/man/supysonic-daemon.rst b/docs/man/supysonic-daemon.rst index d343e29..39acd79 100644 --- a/docs/man/supysonic-daemon.rst +++ b/docs/man/supysonic-daemon.rst @@ -2,37 +2,41 @@ supysonic-daemon ================ ------------------------- -Supysonic scanner daemon ------------------------- +--------------------------- +Supysonic background daemon +--------------------------- -:Author: Louis-Philippe Véronneau -:Date: 2019 +:Author: Louis-Philippe Véronneau, Alban Féron +:Date: 2019, 2021 :Manual section: 1 Synopsis ======== -| supysonic-daemon +``supysonic-daemon`` Description =========== -| **supysonic-daemon** is an optional non-exiting process made to be ran in the -| background to manage background scans and library changes detection. +``supysonic-daemon`` is an optional non-exiting process made to be ran in the +background to manage background scans, library changes detection and the jukebox +mode (audio played on the server hardware). -| If **supysonic-daemon** is running when you start a manual scan using -| **supysonic-cli(1)**, the scan will be run by the daemon process in the -| background instead of running in the foreground. This daemon also enables the -| web UI scan feature. +If ``supysonic-daemon`` is running when you start a manual scan using +``supysonic-cli``\ (1), the scan will be run by the daemon process in the +background instead of running in the foreground. This daemon also enables the +web UI scan feature. + +With proper configuration, ``supysonic-daemon`` also allows authorized users to +play audio on the machine's hardware, using their client as a remote control. Bugs ==== -| Bugs can be reported to your distribution's bug tracker or upstream -| at https://github.com/spl0k/supysonic/issues. +Bugs can be reported to your distribution's bug tracker or upstream +at https://github.com/spl0k/supysonic/issues. See Also ======== -supysonic-cli(1) +``supysonic-cli``\ (1)