Sphinx config, sidebar, etc.

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)

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,
+    ),
+]

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

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

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:
+Sample configuration::
-
-.. code-block:: ini
 
    [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:
+Sample configuration::
-
-.. code-block:: ini
 
    [webapp]
    ; Optional cache directory. Default: /tmp/supysonic
@@ -218,9 +216,7 @@ library folders and providing the jukebox feature.
 
    Defaults to ``WARNING``.
 
-Sample configuration:
+Sample configuration::
-
-.. code-block:: ini
 
    [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:
+Sample configuration::
-
-.. code-block:: ini
 
    [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

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()

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
+setting one of those, you'll want to call the :py:func:`create_application`
-function from module :mod:`supysonic.web`.
+factory function from module :py:mod:`supysonic.web`.

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

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,

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:
+To include track metadata in the transcoded stream::
-
-.. code-block:: ini
 
    [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 -