From 78337265bede08f62e4f2e41fd8a6a6e0b34edb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alban=20F=C3=A9ron?= Date: Sun, 17 Jan 2021 17:06:44 +0100 Subject: [PATCH] Sphinx config, sidebar, etc. --- docs/Makefile | 20 ++++++++ docs/conf.py | 88 +++++++++++++++++++++++++++++++++ docs/index.rst | 3 +- docs/man/index.rst | 6 +-- docs/setup/configuration.rst | 24 ++++----- docs/setup/deploying/apache.rst | 4 +- docs/setup/deploying/index.rst | 4 +- docs/setup/deploying/other.rst | 18 ++++--- docs/setup/index.rst | 9 ++-- docs/transcoding.rst | 8 ++- 10 files changed, 143 insertions(+), 41 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/conf.py diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..fd69c42 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,88 @@ +# -- Project information ----------------------------------------------------- + +project = "Supysonic" +author = "Alban Féron" +copyright = "2013-2021, " + author + +version = "0.6.2" +release = "0.6.2" + + +# -- General configuration --------------------------------------------------- + +extensions = [] +templates_path = [] +source_suffix = ".rst" +master_doc = "index" +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +primary_domain = None +highlight_language = "none" + +language = None + + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "alabaster" +html_theme_options = { + "description": "A Python implementation of the Subsonic server API", + "github_user": "spl0k", + "github_repo": "supysonic", +} +html_static_path = [] + +# Default alabaseter sidebars + localtoc +html_sidebars = { + "**": [ + "about.html", + "localtoc.html", + "navigation.html", + "relations.html", + "searchbox.html", + "donate.html", + ] +} + +html_domain_indices = False + + +# -- Options for manual page output ------------------------------------------ + +_man_authors = ["Louis-Philippe Véronneau", author] + +# Man pages, they are writter to be generated directly by `rst2man` so using +# Sphinx to build them will give weird sections, but if we ever need it it's +# there + +# (source start file, name, description, authors, manual section). +man_pages = [ + ( + "man/supysonic-cli", + "supysonic-cli", + "Python implementation of the Subsonic server API", + _man_authors, + 1, + ), + ( + "man/supysonic-cli-user", + "supysonic-cli-user", + "Supysonic user management commands", + _man_authors, + 1, + ), + ( + "man/supysonic-cli-folder", + "supysonic-cli-folder", + "Supysonic folder management commands", + _man_authors, + 1, + ), + ( + "man/supysonic-daemon", + "supysonic-daemon", + "Supysonic background daemon", + _man_authors, + 1, + ), +] diff --git a/docs/index.rst b/docs/index.rst index 571fa55..7ec46f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,8 +17,7 @@ Current supported features are: __ http://www.subsonic.org/ __ https://www.last.fm/ -User's guide ------------- +.. rubric:: User's guide .. toctree:: :maxdepth: 2 diff --git a/docs/man/index.rst b/docs/man/index.rst index b4b5229..a5d55bc 100644 --- a/docs/man/index.rst +++ b/docs/man/index.rst @@ -1,8 +1,7 @@ Man pages ========= -Command-line interface ----------------------- +.. rubric:: Command-line interface .. toctree:: :maxdepth: 2 @@ -11,8 +10,7 @@ Command-line interface supysonic-cli-user supysonic-cli-folder -Daemon ------- +.. rubric:: Daemon .. toctree:: :maxdepth: 2 diff --git a/docs/setup/configuration.rst b/docs/setup/configuration.rst index 02c091c..8f536ba 100644 --- a/docs/setup/configuration.rst +++ b/docs/setup/configuration.rst @@ -41,7 +41,9 @@ This sections defines the database and additional scanning config. path, it requires three slashes, for absolute paths it's also three slashes followed by the absolute path, meaning actually four slashes on Unix systems. - .. code-block:: ini + .. highlight:: ini + + :: ; Relative path database_uri = sqlite:///relative-file.db @@ -72,9 +74,7 @@ This sections defines the database and additional scanning config. Disabled by default, enable it only if you trust your file system as nothing is done to handle broken links or loops. -Sample configuration: - -.. code-block:: ini +Sample configuration:: [base] ; A database URI. Default: sqlite:////tmp/supysonic/supysonic.db @@ -142,9 +142,7 @@ Configuration relative to the HTTP server. case insensitive. Defaults to ``El La Le Las Les Los The``. -Sample configuration: - -.. code-block:: ini +Sample configuration:: [webapp] ; Optional cache directory. Default: /tmp/supysonic @@ -218,9 +216,7 @@ library folders and providing the jukebox feature. Defaults to ``WARNING``. -Sample configuration: - -.. code-block:: ini +Sample configuration:: [daemon] ; Socket file the daemon will listen on for incoming management commands @@ -261,9 +257,7 @@ page on Supysonic's administrative UI. ``secret`` secret key associated to the API key -Sample configuration: - -.. code-block:: ini +Sample configuration:: [lastfm] ; API and secret key to enable scrobbling. http://www.last.fm/api/accounts @@ -282,7 +276,7 @@ have **not** been thoroughly tested. For more details, please refer to the :doc:`transcoding configuration <../transcoding>`. -.. code-block:: ini +:: [transcoding] ; Programs used to convert from one format/bitrate to another. Defaults: none @@ -305,7 +299,7 @@ See the following links for a list of examples: * https://en.wikipedia.org/wiki/Media_type#Common_examples * https://www.iana.org/assignments/media-types/media-types.xhtml -.. code-block:: ini +:: [mimetypes] ; Extension to mimetype mappings in case your system has some trouble guessing diff --git a/docs/setup/deploying/apache.rst b/docs/setup/deploying/apache.rst index eba8af7..2f8eebb 100644 --- a/docs/setup/deploying/apache.rst +++ b/docs/setup/deploying/apache.rst @@ -20,7 +20,9 @@ Creating a `.wsgi` file ----------------------- To run Supysonic within Apache you need a :file:`supysonic.wsgi` file. Create -one somewhere and fill it with the following content:: +one somewhere and fill it with the following content: + +.. code-block:: python3 from supysonic.web import create_application application = create_application() diff --git a/docs/setup/deploying/index.rst b/docs/setup/deploying/index.rst index 3d65ffd..79b4502 100644 --- a/docs/setup/deploying/index.rst +++ b/docs/setup/deploying/index.rst @@ -18,5 +18,5 @@ You'll find some common (and less common) deployment option below: As Supysonic is a WSGI application, you have numerous deployment options available to you. If you want to deploy it to a WSGI server not listed here, look up the server documentation about how to use a WSGI app with it. When -setting one of those, you'll want to call the :func:`create_application` factory -function from module :mod:`supysonic.web`. +setting one of those, you'll want to call the :py:func:`create_application` +factory function from module :py:mod:`supysonic.web`. diff --git a/docs/setup/deploying/other.rst b/docs/setup/deploying/other.rst index 28a9e03..90fa449 100644 --- a/docs/setup/deploying/other.rst +++ b/docs/setup/deploying/other.rst @@ -18,23 +18,27 @@ Creating a `.fcgi` file ^^^^^^^^^^^^^^^^^^^^^^^ First you need to create the FastCGI server file. Let's call it -:file:`supysonic.fcgi`:: +:file:`supysonic.fcgi`: + +.. code-block:: python3 #!/usr/bin/python3 from flup.server.fcgi import WSGIServer from supysonic.web import create_application - if __name__ == '__main__': + if __name__ == "__main__": app = create_application() WSGIServer(app).run() This should be enough for Apache to work, however nginx and older versions of lighttpd need a socket to be explicitly passed to communicate with the FastCGI server. For that to work you need to pass the path to the socket -to the :class:`~flup.server.fcgi.WSGIServer`:: +to the :py:class:`~flup.server.fcgi.WSGIServer`: - WSGIServer(app, bindAddress='/path/to/fcgi.sock').run() +.. code-block:: python3 + + WSGIServer(app, bindAddress="/path/to/fcgi.sock").run() The path has to be the exact same path you define in the server config. @@ -72,7 +76,9 @@ Creating a `.cgi` file ^^^^^^^^^^^^^^^^^^^^^^ First you need to create the CGI application file. Let's call it -:file:`supysonic.cgi`:: +:file:`supysonic.cgi`: + +.. code-block:: python3 #!/usr/bin/python3 @@ -91,6 +97,6 @@ rewrite the URL) or let the server point to the file directly. In Apache for example you can put something like this into the config: -.. sourcecode:: apache +.. code-block:: apache ScriptAlias /supysonic /path/to/the/supysonic.cgi diff --git a/docs/setup/index.rst b/docs/setup/index.rst index cc7e4cb..610c25f 100644 --- a/docs/setup/index.rst +++ b/docs/setup/index.rst @@ -4,8 +4,7 @@ Supysonic setup This guide details the required steps to get a Supysonic instance ready to start serving your music. -TL;DR ------ +.. rubric:: 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 @@ -20,8 +19,7 @@ music is located 😏). This uses `gunicorn`__, but there are __ https://gunicorn.org/ -Table of contents ------------------ +.. rubric:: Table of contents .. toctree:: :maxdepth: 2 @@ -34,8 +32,7 @@ Table of contents .. _docker: -Docker ------- +.. rubric:: 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, diff --git a/docs/transcoding.rst b/docs/transcoding.rst index 34105a7..fe53410 100644 --- a/docs/transcoding.rst +++ b/docs/transcoding.rst @@ -104,9 +104,9 @@ Suggested configuration Here is an example configuration that you could use. This is provided as-is, and some configurations haven't been tested. -Basic configuration: +.. highlight:: ini -.. code-block:: ini +Basic configuration:: [transcoding] transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate %srcpath - @@ -118,9 +118,7 @@ Basic configuration: encoder_ogg = oggenc2 -Q -M %outrate - default_transcode_target = mp3 -To include track metadata in the transcoded stream: - -.. code-block:: ini +To include track metadata in the transcoded stream:: [transcoding] transcoder_mp3_mp3 = lame --quiet --mp3input -b %outrate --tt %title --tl %album --ta %artist --tn %tracknumber/%totaltracks --tv TPOS=%discnumber --tg %genre --ty %year --add-id3v2 %srcpath -