From 5c969e2f538d2a305a39707c43d1cd886a3ec90a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Louis-Philippe=20V=C3=A9ronneau?= Date: Tue, 7 Dec 2021 23:32:48 -0500 Subject: [PATCH] Modify the man pages for sphinx. Closes #225. --- docs/man/README.md | 4 - docs/man/supysonic-cli-folder.rst | 104 ++++++++++++------------ docs/man/supysonic-cli-user.rst | 126 +++++++++++++++--------------- docs/man/supysonic-cli.rst | 79 +++++++++---------- docs/man/supysonic-daemon.rst | 45 +++++------ docs/man/supysonic-server.rst | 91 ++++++++++----------- 6 files changed, 212 insertions(+), 237 deletions(-) delete mode 100644 docs/man/README.md diff --git a/docs/man/README.md b/docs/man/README.md deleted file mode 100644 index a06280a..0000000 --- a/docs/man/README.md +++ /dev/null @@ -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 diff --git a/docs/man/supysonic-cli-folder.rst b/docs/man/supysonic-cli-folder.rst index 66f68cf..3fece67 100644 --- a/docs/man/supysonic-cli-folder.rst +++ b/docs/man/supysonic-cli-folder.rst @@ -1,69 +1,68 @@ -==================== supysonic-cli-folder ==================== ------------------------------------- -Supysonic folder management commands ------------------------------------- +SYNOPSIS +-------- -:Author: Louis-Philippe Véronneau, Alban Féron -:Date: 2019, 2021 -:Manual section: 1 +supysonic-cli folder *--help* -Synopsis -======== +supysonic-cli folder **list** -| ``supysonic-cli folder --help`` -| ``supysonic-cli folder list`` -| ``supysonic-cli folder add`` `name` `path` -| ``supysonic-cli folder delete`` `name` -| ``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... +supysonic-cli folder **add** <*name*> <*path*> -Description -=========== +supysonic-cli folder **delete** <*name*> -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 **scan** [*--force*] [*--background* | *--foreground*] <*name*> -``supysonic-cli folder list`` - List all the folders. +DESCRIPTION +----------- -``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. +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. -``supysonic-cli folder delete`` `name` - Delete the folder called `name`. +ARGUMENTS +--------- -``supysonic-cli folder scan`` [``--force``] [``--background``\|\ ``--foreground``] [`name`]... - Scan the specified folders. If none is given, all the registered folders are - scanned. +**list** + List all the folders. -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 - Shows help and exits. Depending on where this option appears it will either list the - available commands or display help for a specific command. +**delete** <*name*> + Delete the folder called <*name*>. --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. +**scan** [*--force*] [*--background* | *--foreground*] <*name*> + Scan the specified folders. If none is given, all the registered folders + are scanned. ---background - Scan in the background. Requires the ``supysonic-daemon`` to be running +OPTIONS +------- ---foreground - Scan in the foreground, blocking the process while the scan is running +**-h**, **--help** + 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`` -will try to connect to the daemon to initiate a background scan, falling back to -a foreground scan if it isn't available. +**-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. -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:: @@ -73,10 +72,11 @@ Once you've added a folder, you will need to scan it:: $ supysonic-cli folder scan MyLibrary -The audio files residing in `/home/username/Music` will now appear under the -`MyLibrary` folder on the clients. +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)``, +``supysonic-server (1)``, ``supysonic-daemon (1)`` diff --git a/docs/man/supysonic-cli-user.rst b/docs/man/supysonic-cli-user.rst index e08af6f..59e5dbc 100644 --- a/docs/man/supysonic-cli-user.rst +++ b/docs/man/supysonic-cli-user.rst @@ -1,94 +1,98 @@ -================== supysonic-cli-user ================== ----------------------------------- -Supysonic user management commands ----------------------------------- +SYNOPSIS +-------- -:Author: Louis-Philippe Véronneau, Alban Féron -:Date: 2019, 2021 -:Manual section: 1 +supysonic-cli user *--help* -Synopsis -======== +supysonic-cli user **list** -| ``supysonic-cli user --help`` -| ``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` +supysonic-cli user **add** <*user*> [*--password* <*password*>] [*--email* <*email*>] -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. -``supysonic-cli user list`` - List all the users. +ARGUMENTS +--------- -``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. +**list** + List all the users. -``supysonic-cli user delete`` `user` - Delete the user `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 changepass`` `user` [``--password`` `password`] - Change the password of user `user`. Will prompt for the new password if not - provided. +**delete** <*user*> + Delete the user <*user*>. -``supysonic-cli user setroles`` [``--admin``\|\ ``--noadmin``] [``--jukebox``\|\ ``--nojukebox``] `user` - Give or remove rights to user `user`. +**changepass** <*user*> [*--password* <*password*>] + Change the password of user <*user*>. Will prompt for the new password if + not provided. -``supysonic-cli user rename`` `user` `newname` - Rename the user `user` to `newname` +**setroles** [*--admin* | *--noadmin*] [*--jukebox* | *--nojukebox*] <*user*> + Give or remove rights to user <*user*>. -Options -======= +**rename** <*user*> <*newname*> + Rename the user <*user*> to <*newname*>. --h, --help - Shows help and exits. Depending on where this option appears it will either list the - available commands or display help for a specific command. +OPTIONS +------- --p password, --password password - Specify the user's password upon creation. +**-h**, **--help** + 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 - Specify the user's email. +**-p** <*password*>, **--password** <*password*> + 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 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. +mutually exclusive. --A, --admin - Grant admin rights. +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, --noadmin - Revoke admin rights. +**-A**, **--admin** + Grant admin rights. --J, --jukebox - Grant jukebox rights. +**-a**, **--noadmin** + Revoke admin rights. --j, --nojukebox - Revoke jukebox rights. +**-J**, **--jukebox** + 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 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)`` diff --git a/docs/man/supysonic-cli.rst b/docs/man/supysonic-cli.rst index 76cdbf2..aef0e8b 100644 --- a/docs/man/supysonic-cli.rst +++ b/docs/man/supysonic-cli.rst @@ -1,35 +1,29 @@ -============= supysonic-cli ============= -------------------------------------------- -Supysonic management command line interface -------------------------------------------- +SYNOPSIS +-------- -:Author: Louis-Philippe Véronneau, Alban Féron -:Date: 2019, 2021 -:Manual section: 1 +supysonic-cli *--help* -Synopsis -======== +supysonic-cli **user** [*options*] -| ``supysonic-cli --help`` -| ``supysonic-cli`` [`subcommand`] +supysonic-cli **folder** [*options*] -Description -=========== +DESCRIPTION +----------- 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 -| * transcoding -| * user or random playlists -| * cover arts (as image files in the same folder as music files) -| * starred tracks/albums and ratings -| * Last.FM scrobbling -| * Jukebox mode +* browsing (by folders or tags) +* streaming of various audio file formats +* transcoding +* user or random playlists +* 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. @@ -37,35 +31,36 @@ music collection over HTTP. The command-line interface is an interface allowing administration operations without the use of the web interface. -Options -======= +SUBCOMMANDS +----------- --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. +supysonic-cli has two different subcommands: -Subcommands -=========== - -``supysonic-cli`` has two different subcommands: - -``user`` `args` ... +**user** [*options*] User management commands -``folder`` `args` ... - Folder managemnt commands +**folder** [*options*] + Folder management 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 -==== +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 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)`` diff --git a/docs/man/supysonic-daemon.rst b/docs/man/supysonic-daemon.rst index 39acd79..3b076ed 100644 --- a/docs/man/supysonic-daemon.rst +++ b/docs/man/supysonic-daemon.rst @@ -1,42 +1,33 @@ -================ supysonic-daemon ================ ---------------------------- -Supysonic background daemon ---------------------------- +SYNOPSIS +-------- -:Author: Louis-Philippe Véronneau, Alban Féron -:Date: 2019, 2021 -:Manual section: 1 +supysonic-daemon -Synopsis -======== +DESCRIPTION +----------- -``supysonic-daemon`` - -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, 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**, 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 +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 -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 -======== +SEE ALSO +-------- -``supysonic-cli``\ (1) +``supysonic-cli (1)`` diff --git a/docs/man/supysonic-server.rst b/docs/man/supysonic-server.rst index 6bf657b..ba32f30 100644 --- a/docs/man/supysonic-server.rst +++ b/docs/man/supysonic-server.rst @@ -1,68 +1,57 @@ -================ supysonic-server ================ ------------------------------------------------- -Python implementation of the Subsonic server API ------------------------------------------------- +SYNOPSIS +-------- -:Author: Alban Féron -:Date: 2021 -:Manual section: 1 +supysonic-server [**--server** *gevent* | *gunicorn* | *waitress*] [**--host** <*hostname*>] [**--port** <*port*>] [**--socket** <*path*>] [**--processes** <*n*>] [**--threads** <*n*>] -Synopsis -======== +DESCRIPTION +----------- -``supysonic-server`` [``--server`` ``gevent``\|\ ``gunicorn``\|\ ``waitress``] -[``--host`` `hostname`] [``--port`` `port`] [``--socket`` `path`] -[``--processes`` `n`] [``--threads`` `n`] +**supysonic-server** is the main supysonic's component, allowing to serve +content to clients. It is actually a basic wrapper over **Gevent**, **Gunicorn** +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 -content to clients. It is actually a basic wrapper over ``Gevent``, ``Gunicorn`` -or ``Waitress``, requiring at least one of them to be installed to run. +**-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. -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 - 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. +**-p** <*port*>, **--port** <*port*> + TCP port on which to listen. Default is ``5722``. + Cannot be used with **--socket**. --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** <*path*>, **--socket** <*path*> + 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. + Cannot be used with **--host** or **--port**. + Not available on Windows. --p port, --port port - TCP port on which to listen. Default is ``5722``. - Cannot be used with ``--socket``. +**--processes** <*n*> + Number of worker processes to spawn. Only applicable when using the + **Gunicorn** WSGI server. --s path, --socket path - 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. - Cannot be used with ``--host`` or ``--port``. - Not available on Windows. +**--threads** <*n*> + The number of worker threads for handling requests. Only applicable when + using the **Gunicorn** or **Waitress** WSGI server. ---processes n - Number of worker processes to spawn. Only applicable when using the - ``Gunicorn`` WSGI server (``--server gunicorn``). +BUGS +---- ---threads n - The number of worker threads for handling requests. Only applicable when - using the ``Gunicorn`` or ``Waitress`` WSGI server (``--server gunicorn`` or - ``--server waitress``) +Bugs can be reported to your distribution's bug tracker or upstream at +https://github.com/spl0k/supysonic/issues. -Bugs -==== +SEE ALSO +-------- -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)``