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

Modify the man pages for sphinx.

Browse Source 
Closes #225.
This commit is contained in:
Louis-Philippe Véronneau 2021-12-07 23:32:48 -05:00
parent 430d5a0dad
commit 5c969e2f53
No known key found for this signature in database
GPG Key ID: F4257A50B21CFA85
6 changed files with 212 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/man/README.md
View File

@ -1,4 +0,0 @@
The man pages in this directory can be generated using the `rst2man` command
line tool provided by the Python `docutils` project:
$ rst2man supysonic-cli.rst supysonic.1

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

@ -1,69 +1,68 @@
====================
supysonic-cli-folder supysonic-cli-folder
==================== ====================
------------------------------------ SYNOPSIS
Supysonic folder management commands --------
------------------------------------
:Author: Louis-Philippe Véronneau, Alban Féron supysonic-cli folder *--help*
:Date: 2019, 2021
:Manual section: 1
Synopsis supysonic-cli folder **list**
========
| ``supysonic-cli folder --help`` supysonic-cli folder **add** <*name*> <*path*>
| ``supysonic-cli folder list``
| ``supysonic-cli folder add`` `name` `path`
| ``supysonic-cli folder delete`` `name`
| ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]...
Description supysonic-cli folder **delete** <*name*>
===========
The ``supysonic-cli folder`` subcommand manages your library folders, where the supysonic-cli folder **scan** [*--force*] [*--background* | *--foreground*] <*name*>
audio files are located. This allows to list, add, delete and scan the folders.
``supysonic-cli folder list`` DESCRIPTION
List all the folders. -----------
``supysonic-cli folder add`` `name` `path` The **supysonic-cli folder** subcommand manages your library folders, where the
Add a new library folder called `name` and located at `path`. `name` must be audio files are located. This allows one to list, add, delete and scan the
unique and `path` pointing to an existing directory. If ``supysonic-daemon`` folders.
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` ARGUMENTS
Delete the folder called `name`. ---------
``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... **list**
Scan the specified folders. If none is given, all the registered folders are List all the folders.
scanned.
Options **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.
-h, --help **delete** <*name*>
Shows help and exits. Depending on where this option appears it will either list the Delete the folder called <*name*>.
available commands or display help for a specific command.
-f, --force **scan** [*--force*] [*--background* | *--foreground*] <*name*>
Force scan of already known files even if they haven't changed. Might be Scan the specified folders. If none is given, all the registered folders
useful if an update to Supysonic adds new metadata to audio files. are scanned.
--background OPTIONS
Scan in the background. Requires the ``supysonic-daemon`` to be running -------
--foreground **-h**, **--help**
Scan in the foreground, blocking the process while the scan is running Shows help and exits. Depending on where this option appears it will either
list the available commands or display help for a specific command.
If neither ``--background`` nor ``--foreground`` is provided, ``supysonic-cli`` **-f**, **--force**
will try to connect to the daemon to initiate a background scan, falling back to Force scan of already known files even if they haven't changed. Might be
a foreground scan if it isn't available. useful if an update to supysonic adds new metadata to audio files.
Examples **--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.
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:: To add a new folder to your music library, you can do something like this::
@ -73,10 +72,11 @@ 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 The audio files residing in ``/home/username/Music`` will now appear under the
`MyLibrary` folder on the clients. ``MyLibrary`` folder on the clients.
See Also SEE ALSO
======== --------
``supysonic-cli``\ (1), ``supysonic-cli-user``\ (1) ``supysonic-cli (1)``, ``supysonic-cli-user (1)``,
``supysonic-server (1)``, ``supysonic-daemon (1)``

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

@ -1,94 +1,98 @@
==================
supysonic-cli-user supysonic-cli-user
================== ==================
---------------------------------- SYNOPSIS
Supysonic user management commands --------
----------------------------------
:Author: Louis-Philippe Véronneau, Alban Féron supysonic-cli user *--help*
:Date: 2019, 2021
:Manual section: 1
Synopsis supysonic-cli user **list**
========
| ``supysonic-cli user --help`` supysonic-cli user **add** <*user*> [*--password* <*password*>] [*--email* <*email*>]
| ``supysonic-cli user list``
| ``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`]
| ``supysonic-cli user delete`` `user`
| ``supysonic-cli user changepass`` `user` [``--password`` `password`]
| ``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user`
| ``supysonic-cli user rename`` `user` `newname`
Description supysonic-cli user **delete** <*user*>
===========
The ``supysonic-cli user`` subcommand manages users, allowing to list them, add supysonic-cli user **changepass** <*user*> [*--password* <*password*>]
supysonic-cli user **setroles** [*--admin* | *--noadmin*] [*--jukebox* | *--nojukebox*] <*user*>
supysonic-cli user **rename** <*user*> <*newname*>
DESCRIPTION
-----------
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. a new user, delete an existing user, and change their password or roles.
``supysonic-cli user list`` ARGUMENTS
List all the users. ---------
``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] **list**
Add a new user named `user`. Will prompt for a password if it isn't given List all the users.
with the ``--password`` option.
``supysonic-cli user delete`` `user` **add** <*user*> [*--password* <*password*>] [*--email* <*email*>]
Delete the user `user`. Add a new user named <*user*>. Will prompt for a password if it isn't given
with the *--password* option.
``supysonic-cli user changepass`` `user` [``--password`` `password`] **delete** <*user*>
Change the password of user `user`. Will prompt for the new password if not Delete the user <*user*>.
provided.
``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` **changepass** <*user*> [*--password* <*password*>]
Give or remove rights to user `user`. Change the password of user <*user*>. Will prompt for the new password if
not provided.
``supysonic-cli user rename`` `user` `newname` **setroles** [*--admin* | *--noadmin*] [*--jukebox* | *--nojukebox*] <*user*>
Rename the user `user` to `newname` Give or remove rights to user <*user*>.
Options **rename** <*user*> <*newname*>
======= Rename the user <*user*> to <*newname*>.
-h, --help OPTIONS
Shows help and exits. Depending on where this option appears it will either list the -------
available commands or display help for a specific command.
-p password, --password password **-h**, **--help**
Specify the user's password upon creation. Shows help and exits. Depending on where this option appears it will either
list the available commands or display help for a specific command.
-e email, --email email **-p** <*password*>, **--password** <*password*>
Specify the user's email. Specify the user's password upon creation.
**-e** <*email*>, **--email** <*email*>
Specify the user's email.
The next options relate to user roles. They work in pairs, one option granting 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 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 mutually exclusive.
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 The long options are named with the matching right, prefix it with a **no** to
Grant admin rights. 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, --noadmin **-A**, **--admin**
Revoke admin rights. Grant admin rights.
-J, --jukebox **-a**, **--noadmin**
Grant jukebox rights. Revoke admin rights.
-j, --nojukebox **-J**, **--jukebox**
Revoke jukebox rights. Grant jukebox rights.
Examples **-j**, **--nojukebox**
======== Revoke jukebox rights.
To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: EXAMPLES
--------
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
See Also SEE ALSO
======== --------
``supysonic-cli``\ (1), ``supysonic-cli-folder``\ (1) ``supysonic-cli (1)``, ``supysonic-cli-folder (1)``,
``supysonic-server (1)``, ``supysonic-daemon (1)``

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

@ -1,35 +1,29 @@
=============
supysonic-cli supysonic-cli
============= =============
------------------------------------------- SYNOPSIS
Supysonic management command line interface --------
-------------------------------------------
:Author: Louis-Philippe Véronneau, Alban Féron supysonic-cli *--help*
:Date: 2019, 2021
:Manual section: 1
Synopsis supysonic-cli **user** [*options*]
========
| ``supysonic-cli --help`` supysonic-cli **folder** [*options*]
| ``supysonic-cli`` [`subcommand`]
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
| * transcoding * transcoding
| * user or random playlists * user or random playlists
| * 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 * Jukebox mode
The "Subsonic API" is a set of adhoc standards to browse, stream or download a The "Subsonic API" is a set of adhoc standards to browse, stream or download a
music collection over HTTP. music collection over HTTP.
@ -37,35 +31,36 @@ music collection over HTTP.
The command-line interface is an interface allowing administration operations The command-line interface is an interface allowing administration operations
without the use of the web interface. without the use of the web interface.
Options SUBCOMMANDS
======= -----------
-h, --help supysonic-cli has two different subcommands:
Shows the help and exits. At top level it only lists the subcommands. To
display the help of a specific subcommand, add the ``--help`` flag *after*
the said subcommand name.
Subcommands **user** [*options*]
===========
``supysonic-cli`` has two different subcommands:
``user`` `args` ...
User management commands User management commands
``folder`` `args` ... **folder** [*options*]
Folder managemnt commands Folder management commands
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 OPTIONS
==== -------
**-h**, **--help**
Shows the help and exits. At top level it only lists the subcommands. To
display the help of a specific subcommand, add the **--help** flag *after*
the said subcommand name.
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)``,
``supysonic-server (1)``, ``supysonic-daemon (1)``

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

@ -1,42 +1,33 @@
================
supysonic-daemon supysonic-daemon
================ ================
--------------------------- SYNOPSIS
Supysonic background daemon --------
---------------------------
:Author: Louis-Philippe Véronneau, Alban Féron supysonic-daemon
:Date: 2019, 2021
:Manual section: 1
Synopsis DESCRIPTION
======== -----------
``supysonic-daemon`` **supysonic-daemon** is an optional non-exiting process made to be ran in the
Description
===========
``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 background to manage background scans, library changes detection and the jukebox
mode (audio played on the server hardware). 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**, the scan will be run by the daemon process in the background
background instead of running in the foreground. This daemon also enables the instead of running in the foreground. This daemon also enables the web UI scan
web UI scan feature. feature.
With proper configuration, ``supysonic-daemon`` also allows authorized users to With proper configuration, **supysonic-daemon** also allows authorized users to
play audio on the machine's hardware, using their client as a remote control. 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
at https://github.com/spl0k/supysonic/issues. https://github.com/spl0k/supysonic/issues.
See Also SEE ALSO
======== --------
``supysonic-cli``\ (1) ``supysonic-cli (1)``

91
docs/man/supysonic-server.rst
View File

@ -1,68 +1,57 @@
================
supysonic-server supysonic-server
================ ================
------------------------------------------------ SYNOPSIS
Python implementation of the Subsonic server API --------
------------------------------------------------
:Author: Alban Féron supysonic-server [**--server** *gevent* | *gunicorn* | *waitress*] [**--host** <*hostname*>] [**--port** <*port*>] [**--socket** <*path*>] [**--processes** <*n*>] [**--threads** <*n*>]
:Date: 2021
:Manual section: 1
Synopsis DESCRIPTION
======== -----------
``supysonic-server`` [``--server`` ``gevent``\|\ ``gunicorn``\|\ ``waitress``] **supysonic-server** is the main supysonic's component, allowing to serve
[``--host`` `hostname`] [``--port`` `port`] [``--socket`` `path`] content to clients. It is actually a basic wrapper over **Gevent**, **Gunicorn**
[``--processes`` `n`] [``--threads`` `n`] or **Waitress**, requiring at least one of them to be installed to run.
Description OPTIONS
=========== -------
``supysonic-server`` is the main Supysonic's component, allowing to serve **-S** <*name*>, **--server** <*name*>
content to clients. It is actually a basic wrapper over ``Gevent``, ``Gunicorn`` Specify which WSGI server to use. <*name*> must be one of ``gevent``,
or ``Waitress``, requiring at least one of them to be installed to run. ``gunicorn`` or ``waitress`` and the matching package must then be
installed. If the option isn't provided, the first one available will be
used.
Options **-h** <*hostname*>, **--host** <*hostname*>
======= Hostname or IP address on which to listen. The default is ``0.0.0.0`` which
means to listen on all IPv4 interfaces on this host.
Cannot be used with **--socket**.
-S name, --server name **-p** <*port*>, **--port** <*port*>
Specify which WSGI server to use. `name` must be one of ``gevent``, TCP port on which to listen. Default is ``5722``.
``gunicorn`` or ``waitress`` and the matching package must then be installed. Cannot be used with **--socket**.
If the option isn't provided, the first one available will be used.
-h hostname, --host hostname **-s** <*path*>, **--socket** <*path*>
Hostname or IP address on which to listen. The default is ``0.0.0.0`` which Path of a Unix socket on which to bind to. If a path is specified, a Unix
means to listen on all IPv4 interfaces on this host. domain socket is made instead of the usual inet domain socket.
Cannot be used with ``--socket``. Cannot be used with **--host** or **--port**.
Not available on Windows.
-p port, --port port **--processes** <*n*>
TCP port on which to listen. Default is ``5722``. Number of worker processes to spawn. Only applicable when using the
Cannot be used with ``--socket``. **Gunicorn** WSGI server.
-s path, --socket path **--threads** <*n*>
Path of a Unix socket on which to bind to. If a path is specified, a Unix The number of worker threads for handling requests. Only applicable when
domain socket is made instead of the usual inet domain socket. using the **Gunicorn** or **Waitress** WSGI server.
Cannot be used with ``--host`` or ``--port``.
Not available on Windows.
--processes n BUGS
Number of worker processes to spawn. Only applicable when using the ----
``Gunicorn`` WSGI server (``--server gunicorn``).
--threads n Bugs can be reported to your distribution's bug tracker or upstream at
The number of worker threads for handling requests. Only applicable when https://github.com/spl0k/supysonic/issues.
using the ``Gunicorn`` or ``Waitress`` WSGI server (``--server gunicorn`` or
``--server waitress``)
Bugs SEE ALSO
==== --------
Bugs can be reported to your distribution's bug tracker or upstream ``supysonic-cli (1)``
at https://github.com/spl0k/supysonic/issues.
See Also
========
``supysonic-cli``\ (1)