github/supysonic
1
0
Fork 0
mirror of https://github.com/spl0k/supysonic.git synced 2024-12-22 17:06:17 +00:00
Code Issues Releases Wiki Activity

Improve manpages

Browse Source
This commit is contained in:
Alban Féron 2021-01-03 16:34:29 +01:00
parent c8db5b81ab
commit fb41bf2814
No known key found for this signature in database
GPG Key ID: 8CE0313646D16165
6 changed files with 142 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
docs/cli.md
View File

@ -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 <arguments>`).
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 <user> [-p <password>] [-e <email>]
supysonic-cli user delete <user>
supysonic-cli user changepass <user> <password>
supysonic-cli user list
supysonic-cli user setroles [-a|-A] [-j|-J] <user>
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 <password> Specify the user's password
-e --email <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 <name> <path>
supysonic-cli folder delete <name>
supysonic-cli folder list
supysonic-cli folder scan [-f] [--background | --foreground] [<name>...]
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
```

3
docs/jukebox.rst
View File

@ -39,6 +39,7 @@ Allowing users to act on the jukebox
------------------------------------ ------------------------------------
The jukebox mode is only accessible to chosen users. Granting (or revoking) 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 <man/supysonic-cli-user>`::
$ supysonic-cli user setroles --jukebox <username> $ supysonic-cli user setroles --jukebox <username>

60
docs/man/supysonic-cli-folder.rst
View File

@ -6,37 +6,56 @@ supysonic-cli-folder
Supysonic folder management commands Supysonic folder management commands
------------------------------------ ------------------------------------
:Author: Louis-Philippe Véronneau :Author: Louis-Philippe Véronneau, Alban Féron
:Date: 2019 :Date: 2019, 2021
:Manual section: 1 :Manual section: 1
Synopsis Synopsis
======== ========
| supysonic-cli folder **add** <name> <path> | ``supysonic-cli folder list``
| supysonic-cli folder **delete** <name> | ``supysonic-cli folder add`` `name` `path`
| supysonic-cli folder **list** | ``supysonic-cli folder delete`` `name`
| supysonic-cli folder **scan** [-f] [--background | --foreground] [<name>...] | ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]...
Arguments Description
========= ===========
| **add** Add a new folder The ``supysonic-cli folder`` subcommand manages your library folders, where the
| **delete** Delete a folder audio files are located. This allows to list, add, delete and scan the folders.
| **list** List all the folders
| **scan** Scan all or specified 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 Options
======= =======
| **-f** | **--force** -f, --force
|     Force scan of already known files even if they haven't changed 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** --background
|     Scan in the background. Requires the daemon to be running Scan in the background. Requires the ``supysonic-daemon`` to be running
| **--foreground** --foreground
|     Scan in the foreground, blocking the process while the scan is running 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 Examples
======== ========
@ -49,7 +68,10 @@ 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 See Also
======== ========
supysonic-cli(1), supysonic-cli-user(1) ``supysonic-cli``\ (1), ``supysonic-cli-user``\ (1)

76
docs/man/supysonic-cli-user.rst
View File

@ -6,53 +6,75 @@ supysonic-cli-user
Supysonic user management commands Supysonic user management commands
---------------------------------- ----------------------------------
:Author: Louis-Philippe Véronneau :Author: Louis-Philippe Véronneau, Alban Féron
:Date: 2019 :Date: 2019, 2021
:Manual section: 1 :Manual section: 1
Synopsis Synopsis
======== ========
| supysonic-cli user **add** <user> [-p <password>] [-e <email>] | ``supysonic-cli user list``
| supysonic-cli user **delete** <user> | ``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`]
| supysonic-cli user **changepass** <user> <password> | ``supysonic-cli user delete`` `user`
| supysonic-cli user **list** | ``supysonic-cli user changepass`` `user` `password`
| supysonic-cli user **setroles** [-a|-A] [-j|-J] <user> | ``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user`
Arguments Description
========= ===========
| **add** Add a new user The ``supysonic-cli user`` subcommand manages users, allowing to list them, add
| **delete** Delete the user a new user, delete an existing user, and change their password or roles.
| **changepass** Change the user's password
| **list** List all the users ``supysonic-cli user list``
| **setroles** Give or remove rights to the user 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 Options
======= =======
| **-p** | **--password** *<password>* -p password, --password password
|     Specify the user's password Specify the user's password upon creation.
| **-e** | **--email** *<email>* -e email, --email email
|     Specify the user's email Specify the user's email.
| **-a** | **--noadmin** The next options relate to user roles. They work in pairs, one option granting
|     Revoke admin rights 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** -A, --admin
|     Grant admin rights Grant admin rights.
| **-j** | **--nojukebox** -a, --noadmin
|     Revoke jukebox rights Revoke admin rights.
| **-J** | **--jukebox** -J, --jukebox
|     Grant jukebox rights Grant jukebox rights.
-j, --nojukebox
Revoke jukebox rights.
Examples 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 add MyUserName -p MyAwesomePassword
$ supysonic-cli user setroles -A MyUserName $ supysonic-cli user setroles -A MyUserName

51
docs/man/supysonic-cli.rst
View File

@ -6,25 +6,21 @@ supysonic-cli
Python implementation of the Subsonic server API Python implementation of the Subsonic server API
------------------------------------------------ ------------------------------------------------
:Author: Louis-Philippe Véronneau :Author: Louis-Philippe Véronneau, Alban Féron
:Date: 2019 :Date: 2019, 2021
:Manual section: 1 :Manual section: 1
Synopsis Synopsis
======== ========
| supysonic-cli [**subcommand**] | ``supysonic-cli`` [`subcommand`]
| supysonic-cli **help** | ``supysonic-cli help`` [`subcommand`]
| supysonic-cli **help** *user*
| supysonic-cli **help** *folder*
Description Description
=========== ===========
| supysonic is a Python implementation of the Subsonic server API. Supysonic is a Python implementation of the Subsonic server API.
| Current supported features are: Current supported features are:
|
| * browsing (by folders or tags) | * browsing (by folders or tags)
| * streaming of various audio file formats | * streaming of various audio file formats
@ -33,34 +29,41 @@ Description
| * cover arts (as image files in the same folder as music files) | * cover arts (as image files in the same folder as music files)
| * starred tracks/albums and ratings | * starred tracks/albums and ratings
| * Last.FM scrobbling | * Last.FM scrobbling
| * Jukebox mode
| The "Subsonic API" is a set of adhoc standards to browse, stream or The "Subsonic API" is a set of adhoc standards to browse, stream or download a
| download a music collection over HTTP. 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 Subcommands
=========== ===========
| If ran without arguments, **supysonic-cli** will open an interactive ``supysonic-cli`` has three different subcommands:
| prompt.
**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 ``folder`` `args` ...
| * user Folder managemnt commands
| * folder
| For more details on the **user** and **folder** subcommands, see the For more details on the ``user`` and ``folder`` subcommands, see the
| subsonic-cli-user(1), subsonic-cli-folder(1) manual pages. ``subsonic-cli-user``\ (1), ``subsonic-cli-folder``\ (1) manual pages.
Bugs Bugs
==== ====
| Bugs can be reported to your distribution's bug tracker or upstream Bugs can be reported to your distribution's bug tracker or upstream
| at https://github.com/spl0k/supysonic/issues. at https://github.com/spl0k/supysonic/issues.
See Also See Also
======== ========
supysonic-cli-user(1), supysonic-cli-folder(1) ``supysonic-cli-user``\ (1), ``supysonic-cli-folder``\ (1)

34
docs/man/supysonic-daemon.rst
View File

@ -2,37 +2,41 @@
supysonic-daemon supysonic-daemon
================ ================
------------------------ ---------------------------
Supysonic scanner daemon Supysonic background daemon
------------------------ ---------------------------
:Author: Louis-Philippe Véronneau :Author: Louis-Philippe Véronneau, Alban Féron
:Date: 2019 :Date: 2019, 2021
:Manual section: 1 :Manual section: 1
Synopsis Synopsis
======== ========
| supysonic-daemon ``supysonic-daemon``
Description Description
=========== ===========
| **supysonic-daemon** is an optional non-exiting process made to be ran in the ``supysonic-daemon`` is an optional non-exiting process made to be ran in the
| background to manage background scans and library changes detection. 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 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 ``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 background instead of running in the foreground. This daemon also enables the
| web UI scan feature. 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
==== ====
| Bugs can be reported to your distribution's bug tracker or upstream Bugs can be reported to your distribution's bug tracker or upstream
| at https://github.com/spl0k/supysonic/issues. at https://github.com/spl0k/supysonic/issues.
See Also See Also
======== ========
supysonic-cli(1) ``supysonic-cli``\ (1)