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

100
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
-----------
The **supysonic-cli folder** subcommand manages your library folders, where the
audio files are located. This allows one to list, add, delete and scan the
folders.
ARGUMENTS
---------
**list**
List all the folders. List all the folders.
``supysonic-cli folder add`` `name` `path` **add** <*name*> <*path*>
Add a new library folder called `name` and located at `path`. `name` must be Add a new library folder called <*name*> and located at <*path*>. <*name*>
unique and `path` pointing to an existing directory. If ``supysonic-daemon`` must be unique and <*path*> pointing to an existing directory. If
is running it will start to listen for changes in this folder but will not ``supysonic-daemon`` is running it will start to listen for changes in this
scan files already present in the folder. folder but will not scan files already present in the folder.
``supysonic-cli folder delete`` `name` **delete** <*name*>
Delete the folder called `name`. Delete the folder called <*name*>.
``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... **scan** [*--force*] [*--background* | *--foreground*] <*name*>
Scan the specified folders. If none is given, all the registered folders are Scan the specified folders. If none is given, all the registered folders
scanned. are scanned.
Options OPTIONS
======= -------
-h, --help **-h**, **--help**
Shows help and exits. Depending on where this option appears it will either list the Shows help and exits. Depending on where this option appears it will either
available commands or display help for a specific command. list the available commands or display help for a specific command.
-f, --force **-f**, **--force**
Force scan of already known files even if they haven't changed. Might be 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. useful if an update to supysonic adds new metadata to audio files.
--background **--background**
Scan in the background. Requires the ``supysonic-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`` If neither **--background** nor **--foreground** is provided, supysonic-cli
will try to connect to the daemon to initiate a background scan, falling back to will try to connect to the daemon to initiate a background scan, falling back
a foreground scan if it isn't available. to a foreground scan if it isn't available.
Examples 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)``

112
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**
List all the users. List all the users.
``supysonic-cli user add`` `user` [``--password`` `password`] [``--email`` `email`] **add** <*user*> [*--password* <*password*>] [*--email* <*email*>]
Add a new user named `user`. Will prompt for a password if it isn't given Add a new user named <*user*>. Will prompt for a password if it isn't given
with the ``--password`` option. with the *--password* option.
``supysonic-cli user delete`` `user` **delete** <*user*>
Delete the user `user`. Delete the user <*user*>.
``supysonic-cli user changepass`` `user` [``--password`` `password`] **changepass** <*user*> [*--password* <*password*>]
Change the password of user `user`. Will prompt for the new password if not Change the password of user <*user*>. Will prompt for the new password if
provided. not provided.
``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` **setroles** [*--admin* | *--noadmin*] [*--jukebox* | *--nojukebox*] <*user*>
Give or remove rights to user `user`. Give or remove rights to user <*user*>.
``supysonic-cli user rename`` `user` `newname` **rename** <*user*> <*newname*>
Rename the user `user` to `newname` Rename the user <*user*> to <*newname*>.
Options OPTIONS
======= -------
-h, --help **-h**, **--help**
Shows help and exits. Depending on where this option appears it will either list the Shows help and exits. Depending on where this option appears it will either
available commands or display help for a specific command. list the available commands or display help for a specific command.
-p password, --password password **-p** <*password*>, **--password** <*password*>
Specify the user's password upon creation. Specify the user's password upon creation.
-e email, --email email **-e** <*email*>, **--email** <*email*>
Specify the user's 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
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. Grant admin rights.
-a, --noadmin **-a**, **--noadmin**
Revoke admin rights. Revoke admin rights.
-J, --jukebox **-J**, **--jukebox**
Grant jukebox rights. Grant jukebox rights.
-j, --nojukebox **-j**, **--nojukebox**
Revoke jukebox rights. Revoke jukebox rights.
Examples EXAMPLES
======== --------
To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: 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)``

75
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*>
=======
-S name, --server name
Specify which WSGI server to use. `name` must be one of ``gevent``,
``gunicorn`` or ``waitress`` and the matching package must then be installed.
If the option isn't provided, the first one available will be used.
-h hostname, --host hostname
Hostname or IP address on which to listen. The default is ``0.0.0.0`` which 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. means to listen on all IPv4 interfaces on this host.
Cannot be used with ``--socket``. Cannot be used with **--socket**.
-p port, --port port **-p** <*port*>, **--port** <*port*>
TCP port on which to listen. Default is ``5722``. TCP port on which to listen. Default is ``5722``.
Cannot be used with ``--socket``. Cannot be used with **--socket**.
-s path, --socket path **-s** <*path*>, **--socket** <*path*>
Path of a Unix socket on which to bind to. If a path is specified, a Unix Path of a Unix socket on which to bind to. If a path is specified, a Unix
domain socket is made instead of the usual inet domain socket. domain socket is made instead of the usual inet domain socket.
Cannot be used with ``--host`` or ``--port``. Cannot be used with **--host** or **--port**.
Not available on Windows. Not available on Windows.
--processes n **--processes** <*n*>
Number of worker processes to spawn. Only applicable when using the Number of worker processes to spawn. Only applicable when using the
``Gunicorn`` WSGI server (``--server gunicorn``). **Gunicorn** WSGI server.
--threads n **--threads** <*n*>
The number of worker threads for handling requests. Only applicable when The number of worker threads for handling requests. Only applicable when
using the ``Gunicorn`` or ``Waitress`` WSGI server (``--server gunicorn`` or using the **Gunicorn** or **Waitress** WSGI server.
``--server waitress``)
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)``