From 6d56b56dd5d3ebd4302ba0920c0cefbb5c6479f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 17 Jan 2021 12:29:37 +0100 Subject: [PATCH] Some doc touches --- docs/api.rst | 10 ++++++---- docs/index.rst | 30 +++++++++++++++++++++++++++++ docs/jukebox.rst | 1 + docs/man/index.rst | 20 +++++++++++++++++++ docs/man/supysonic-cli-folder.rst | 2 +- docs/man/supysonic-cli-user.rst | 2 +- docs/setup/configuration.rst | 23 +++++++++++----------- docs/setup/index.rst | 32 +++++++++++++++++++++++++++++++ docs/setup/install.rst | 23 ++++------------------ docs/transcoding.rst | 31 ++++++++++++++++++++---------- 10 files changed, 127 insertions(+), 47 deletions(-) create mode 100644 docs/index.rst create mode 100644 docs/man/index.rst diff --git a/docs/api.rst b/docs/api.rst index 73b075b..0ac0598 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,12 +3,14 @@ Subsonic API breakdown This page lists all the API methods and their parameters up to the version 1.16.0 (Subsonic 6.1.2). Here you'll find details about which API features -*Supysonic* support, plan on supporting, or won't. +Supysonic support, plan on supporting, or won't. At the moment, the current target API version is 1.10.2. The following information was gathered by *diff*-ing various snapshots of the -`Subsonic API page `_. +`Subsonic API page`__. + +__ http://www.subsonic.org/pages/api.jsp Methods and parameters listing ------------------------------ @@ -57,7 +59,7 @@ getSongsByGenre_ 1.9.0 ✔️ getNowPlaying_ ✔️ getStarred_ ✔️ getStarred2_ ✔️ -search_ ✔️ +:ref:`search ` ✔️ search2_ ✔️ search3_ ✔️ getPlaylists_ ✔️ @@ -449,7 +451,7 @@ Album/song lists Searching ^^^^^^^^^ -.. _search: +.. _search-: ``search`` ✔️ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..571fa55 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,30 @@ +Welcome to Supysonic's documentation! +===================================== + +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 + +__ http://www.subsonic.org/ +__ https://www.last.fm/ + +User's guide +------------ + +.. toctree:: + :maxdepth: 2 + + setup/index + transcoding + jukebox + man/index + api diff --git a/docs/jukebox.rst b/docs/jukebox.rst index f241730..30f9bf7 100644 --- a/docs/jukebox.rst +++ b/docs/jukebox.rst @@ -21,6 +21,7 @@ following fields: ``%path`` absolute path of the file to be played + ``%offset`` time in seconds where to start playing (used for seeking) diff --git a/docs/man/index.rst b/docs/man/index.rst new file mode 100644 index 0000000..b4b5229 --- /dev/null +++ b/docs/man/index.rst @@ -0,0 +1,20 @@ +Man pages +========= + +Command-line interface +---------------------- + +.. toctree:: + :maxdepth: 2 + + supysonic-cli + supysonic-cli-user + supysonic-cli-folder + +Daemon +------ + +.. toctree:: + :maxdepth: 2 + + supysonic-daemon diff --git a/docs/man/supysonic-cli-folder.rst b/docs/man/supysonic-cli-folder.rst index 869fbd5..d41dca0 100644 --- a/docs/man/supysonic-cli-folder.rst +++ b/docs/man/supysonic-cli-folder.rst @@ -45,7 +45,7 @@ Options -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. + useful if an update to Supysonic adds new metadata to audio files. --background Scan in the background. Requires the ``supysonic-daemon`` to be running diff --git a/docs/man/supysonic-cli-user.rst b/docs/man/supysonic-cli-user.rst index c25df9e..b4f51d5 100644 --- a/docs/man/supysonic-cli-user.rst +++ b/docs/man/supysonic-cli-user.rst @@ -82,4 +82,4 @@ To add a new admin user named `MyUserName` having password `MyAwesomePassword`:: See Also ======== -supysonic-cli(1), supysonic-cli-folder(1) +``supysonic-cli``\ (1), ``supysonic-cli-folder``\ (1) diff --git a/docs/setup/configuration.rst b/docs/setup/configuration.rst index 5670ae5..02c091c 100644 --- a/docs/setup/configuration.rst +++ b/docs/setup/configuration.rst @@ -13,7 +13,7 @@ If you cloned Supysonic from its `GitHub repository`__ you'll find a roughly documented configuration sample file at the root of the project, file conveniently named :file:`config.sample`. More details below. -__ http://github.com/spl0k/supysonic +__ https://github.com/spl0k/supysonic ``[base]`` section ------------------ @@ -22,7 +22,7 @@ This sections defines the database and additional scanning config. ``database_uri`` The most important configuration, defines the type and - parameters of the database *Supysonic* should connect to. It usually includes + parameters of the database Supysonic should connect to. It usually includes username, password, hostname and database name. The typical form of a database URI is:: @@ -59,7 +59,7 @@ This sections defines the database and additional scanning config. ``utf8mb4`` regardless of what's set on your MySQL installation. If ``database_uri`` isn't provided, it defaults to a SQLite database stored - in ``/tmp/supysonic/supysonic.db``. + in :file:`/tmp/supysonic/supysonic.db`. ``scanner_extensions`` A space separated list of file extensions the scanner is restricted to. @@ -77,8 +77,7 @@ Sample configuration: .. code-block:: ini [base] - ; A database URI. See the 'schema' folder for schema creation scripts - ; Default: sqlite:////tmp/supysonic/supysonic.db + ; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db database_uri = sqlite:////var/supysonic/supysonic.db ;database_uri = mysql://supysonic:supysonic@localhost/supysonic ;database_uri = postgres://supysonic:supysonic@localhost/supysonic @@ -96,7 +95,7 @@ Configuration relative to the HTTP server. ``cache_dir`` Directory used to store generated files, such as resized cover art or - transcoded files. Defaults to ``/tmp/supysonic``. + transcoded files. Defaults to :file:`/tmp/supysonic`. ``cache_size`` Maximum size (in megabytes) of the cache (except for trancodes). @@ -123,8 +122,8 @@ Configuration relative to the HTTP server. Defaults to ``WARNING``. ``mount_api`` (``on`` or ``off``) - Enable or disable the Subsonic REST API. Should be kept on or *Supysonic* - would be quite useless. Exists mostly for testing purposes. + Enable or disable the Subsonic REST API. Should be kept on or Supysonic would + be quite useless. Exists mostly for testing purposes. Defaults to ``on``. ``mount_webui`` (``on`` or ``off``) @@ -187,7 +186,7 @@ library folders and providing the jukebox feature. Unix domain socket file (or named pipe on Windows) used to communicate between the daemon and clients that rely on it (eg. CLI, folder admin web page, etc.). Note that using an IP address here isn't supported. - Default: /tmp/supysonic/supysonic.sock + Default: :file:`/tmp/supysonic/supysonic.sock` ``run_watcher`` Whether or not to start the watcher that will listen for library changes. @@ -248,13 +247,13 @@ Sample configuration: -------------------- This section allow defining API keys to enable Last.FM integration in -*Supysonic*. Currently it is only used to *scrobble* played tracks and update +Supysonic. Currently it is only used to *scrobble* played tracks and update the *now playing* information. See https://www.last.fm/api to obtain such keys. Once keys are set, users have to link their account by visiting their profile -page on *Supysonic*'s administrative UI. +page on Supysonic's administrative UI. ``api_key`` Last.FM API key @@ -298,7 +297,7 @@ For more details, please refer to the ``[mimetypes]`` section ----------------------- -Use this section if the system *Supysonic* is installed on has trouble guessing +Use this section if the system Supysonic is installed on has trouble guessing the mimetype of some files. This might only be useful in some rare cases. See the following links for a list of examples: diff --git a/docs/setup/index.rst b/docs/setup/index.rst index a2a75bc..cc7e4cb 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -4,6 +4,25 @@ Supysonic setup This guide details the required steps to get a Supysonic instance ready to start serving your music. +TL;DR +----- + +For the impatient, here's a quick summary to get Supysonic installed and ready +to start serving (but this doesn't create any user nor specifies where your +music is located 😏). This uses `gunicorn`__, but there are +:doc:`other options `. + +:: + + pip install git+https://github.com/spl0k/supysonic.git + pip install gunicorn + gunicorn -b 0.0.0.0:5000 "supysonic.web:create_application()" + +__ https://gunicorn.org/ + +Table of contents +----------------- + .. toctree:: :maxdepth: 2 @@ -12,3 +31,16 @@ start serving your music. configuration deploying/index daemon + +.. _docker: + +Docker +------ + +Another solution rather than going through the whole setup process yourself is +to use a ready-to-use Docker image. While we don't provide images for Supysonic, +that didn't keep the community from creating some. Take a look on the +`Docker Hub`__ and pick one you like. For more details on their usage, please +refer to the readme of said images. + +__ https://hub.docker.com/search?q=supysonic&type=image diff --git a/docs/setup/install.rst b/docs/setup/install.rst index 2762595..9482c9e 100644 --- a/docs/setup/install.rst +++ b/docs/setup/install.rst @@ -32,8 +32,8 @@ corresponding Python package, ``python-pymysql`` for MySQL or $ apt install python-psycopg2 -For other distributions, you might consider installing from `docker`_ images or -from `source`_. +For other distributions, you might consider installing from :ref:`docker` images +or from `source`_. Windows ------- @@ -60,34 +60,19 @@ to the `source installation instructions `_ below for more information. __ https://docs.python-guide.org/ __ https://docs.python-guide.org/starting/install3/win/ -.. _docker: - -Docker ------- - -While we don't provide Docker images for Supysonic, that didn't keep the -community from creating some. Take a look on the `Docker Hub`__ and pick one you -like. For more details on their usage, please refer to the readme of said -images. - -__ https://hub.docker.com/search?q=supysonic&type=image - .. _source: Source ------ You can install Supysonic directly from a clone of the `Git repository`__. This -can be done either by cloning the repo and installing from the local clone, or -simply installing directly via :command:`pip`. - -:: +can be done either by cloning the repo and installing from the local clone:: $ git clone https://github.com/spl0k/supysonic.git $ cd supysonic $ pip install . -:: +or simply installing directly via :command:`pip`:: $ pip install git+https://github.com/spl0k/supysonic.git diff --git a/docs/transcoding.rst b/docs/transcoding.rst index ba45744..34105a7 100644 --- a/docs/transcoding.rst +++ b/docs/transcoding.rst @@ -6,12 +6,12 @@ allows for streaming of formats that wouldn't be streamable otherwise, or reducing the quality of an audio file to allow a decent streaming for clients with limited bandwidth, such as the ones running on a mobile connection. -Transcoding in *Supysonic* is achieved through the use of third-party -command-line programs. *Supysonic* isn't bundled with such programs, and you are -left to choose which one you want to use. +Transcoding in Supysonic is achieved through the use of third-party command-line +programs. Supysonic isn't bundled with such programs, and you are left to choose +which one you want to use. If you want to use transcoding but your client doesn't allow you to do so, you -can force *Supysonic* to transcode for that client by going to your profile page +can force Supysonic to transcode for that client by going to your profile page on the web interface. Configuration @@ -45,7 +45,7 @@ versions. The programs defined with these variables should be able to transcode/decode/encode any format. For that reason, we suggest you don't use these if you want to keep control over the available transcoders. -*Supysonic* will take the first available transcoding configuration in the +Supysonic will take the first available transcoding configuration in the following order: #. specific transcoder @@ -59,26 +59,37 @@ program. The command-lines can include the following fields: ``%srcpath`` path to the original file to transcode + ``%srcfmt`` extension of the original file + ``%outfmt`` extension of the resulting file + ``%outrate`` bitrate of the resulting file + ``%title`` title of the file to transcode + ``%album`` album name of the file to transcode + ``%artist`` artist name of the file to transcode + ``%tracknumber`` track number of the file to transcode + ``%totaltracks`` number of tracks in the album of the file to transcode + ``%discnumber`` disc number of the file to transcode + ``%genre`` genre of the file to transcode (not always available, defaults to "") + ``%year`` year of the file to transcode (not always available, defaults to "") @@ -126,14 +137,14 @@ Enabling transcoding Once the transcoding configuration has been set, most clients will require the user to specify that they want to transcode files. This might be done on the -client itself, but most importantly it should be done on *Supysonic* web +client itself, but most importantly it should be done on Supysonic web interface. Not doing so might prevent some clients to properly request transcoding. To enable transcoding with the web interface, you should first start using the client you want to set transcoding for. Only browsing the library should suffice. Then open your browser of choice and navigate to the URL of your -*Supysonic* instance. Log in with your credentials and the click on your -username in the top bar. There you should be presented with a list of clients -you used to connect to *Supysonic* and be able to set you preferred streaming -format and bitrate. +Supysonic instance. Log in with your credentials and the click on your username +in the top bar. There you should be presented with a list of clients you used to +connect to Supysonic and be able to set your preferred streaming format +and bitrate.