From a4fa4242a328252a2deb7d3fa9acaa59741dad8e Mon Sep 17 00:00:00 2001 From: kaliko Date: Mon, 7 Jun 2021 14:22:44 +0200 Subject: [PATCH] doc: Update sphinx config, add user documentation Also add SimaDB module documentation --- doc/source/conf.py | 3 ++ doc/source/dev/meta.rst | 9 +++- doc/source/dev/simadb.rst | 8 ++++ doc/source/index.rst | 45 ++++++++++++++++-- doc/source/links.rst | 8 ++++ doc/source/user/00_install.rst | 57 ++++++++++++++++++++++ doc/source/user/01_configurations.rst | 68 +++++++++++++++++++++++++++ doc/source/user/10_metadata.rst | 35 ++++++++++++++ 8 files changed, 226 insertions(+), 7 deletions(-) create mode 100644 doc/source/dev/simadb.rst create mode 100644 doc/source/links.rst create mode 100644 doc/source/user/00_install.rst create mode 100644 doc/source/user/01_configurations.rst create mode 100644 doc/source/user/10_metadata.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 6f553a0..3845855 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -35,6 +35,7 @@ from sima.info import __version__, __author__ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx', ] # Add any paths that contain templates here, relative to this directory. @@ -291,3 +292,5 @@ texinfo_documents = [ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False + +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/doc/source/dev/meta.rst b/doc/source/dev/meta.rst index 906a300..f6f50dc 100644 --- a/doc/source/dev/meta.rst +++ b/doc/source/dev/meta.rst @@ -1,6 +1,8 @@ Track object Documentation ========================== +.. autodata:: SEPARATOR + .. automodule:: sima.lib.track :members: @@ -10,7 +12,7 @@ Meta object Documentation Generic class and helper function --------------------------------- -.. autoclass:: sima.lib.meta.Meta(name, mbid=None, **kwargs) +.. autoclass:: sima.lib.meta.Meta :members: :undoc-members: @@ -19,7 +21,10 @@ Generic class and helper function Derived objects --------------- -.. autoclass:: sima.lib.meta.Artist(name, mbid=None, albumartist=None, musicbrainz_artistid=None, musicbrainz_albumartistid=None) +.. autoclass:: sima.lib.meta.Artist(name, mbid=None, musicbrainz_artistid=None, albumartist=None) + :show-inheritance: + +.. autoclass:: sima.lib.meta.Album :show-inheritance: diff --git a/doc/source/dev/simadb.rst b/doc/source/dev/simadb.rst new file mode 100644 index 0000000..7ab5715 --- /dev/null +++ b/doc/source/dev/simadb.rst @@ -0,0 +1,8 @@ +Database managment module +========================= + +.. automodule:: sima.lib.simadb + :members: + :undoc-members: + +.. autodata:: sima.lib.simadb.__HIST_DURATION__ diff --git a/doc/source/index.rst b/doc/source/index.rst index bd31cac..09f16da 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,14 +3,44 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -MPD_sima's documentation! -========================= +######################### +MPD_sima's documentation +######################### +MPD_sima is meant to **auto-magically queue** tracks in MPD_, it is a non interactive client for MPD_. -Development documentation -------------------------- +Actually there is no magic involved, it relies on music metadata found in music +files tags and external information providers such as last.fm_. Then to use +MPD_sima (or any advanced music players, MPD_ among them), you need to ensure +your library is correctly tagged (see :ref:`metadata-convention`). + +The default setting for MPD_sima is to queue similar artists thanks to last.fm_ +suggestions but there are other possibilities. + +**To queue tracks from similar artists, start playing a track in MPD then launch MPD_sima:** + +.. code-block:: sh -**Contents:** + # runs against localhost MPD (or whatever is set in MPD_HOST/MPD_PORT) + mpd-sima + + # runs against a specific MPD server + mpd-sima --host mpd.example.org + +##################### +User's documentation +##################### + +.. toctree:: + :maxdepth: 2 + :glob: + + user/* + + +########################## +Development documentation +########################## .. toctree:: :maxdepth: 2 @@ -20,6 +50,7 @@ Development documentation dev/meta dev/lastfm dev/cache + dev/simadb Indices and tables @@ -29,3 +60,7 @@ Indices and tables * :ref:`modindex` * :ref:`search` + +.. include:: links.rst + +.. vim: spell spelllang=en diff --git a/doc/source/links.rst b/doc/source/links.rst new file mode 100644 index 0000000..cd326df --- /dev/null +++ b/doc/source/links.rst @@ -0,0 +1,8 @@ +.. _picard: https://picard.musicbrainz.org/ +.. _beets: https://beets.io/ +.. _mpd: https://musicpd.org/ +.. _MusicBrainzIDs: https://musicbrainz.org/doc/MusicBrainz_Identifier +.. _MBIDs: https://musicbrainz.org/doc/MusicBrainz_Identifier +.. _MusicBrainz: https://musicbrainz.org +.. _`ID3 tags`: https://en.wikipedia.org/wiki/ID3 +.. _last.fm: https://www.last.fm/ diff --git a/doc/source/user/00_install.rst b/doc/source/user/00_install.rst new file mode 100644 index 0000000..703b8db --- /dev/null +++ b/doc/source/user/00_install.rst @@ -0,0 +1,57 @@ +Installation +============ + +\*nix distributions +------------------- + +Use your package manager, there are packages for Debian (and probably derivatives) and Arch via AUR. + + +Python virtualenv +----------------- + +.. code:: bash + + # create venv + python -m venv mpd_sima-venv + # activate + . ./mpd_sima-venv/bin/activate + # Install the application + pip install MPD_sima + # Print help message + mpd-sima --help + +From Source +----------- + +Virtualenv installation from source: + +Run ``python ./vinstall.py`` from the source to generate the python virtualenv and install requirements. + +It will setup a virtualenv within a "venv" directory (same level as vinstall.py file). It should also write a shell wrapper to run mpd-sima within the virtualenv. + + +.. code:: bash + + # Clone master branch + git clone -b master git@gitlab.com:kaliko/sima.git + # setup virtualenv + python ./vinstall.py + ./vmpd-sima --help + +To restart from scratch or pull latest changes + +.. code:: bash + + # Get into the local git repo (here sima directory) + cd sima + # Remove virtualenv + rm -rf ./venv + # Fetch and merge latest changes + git pull + # setup virtualenv + python ./vinstall.py + ./vmpd-sima --help + + +.. vim: spell spelllang=en diff --git a/doc/source/user/01_configurations.rst b/doc/source/user/01_configurations.rst new file mode 100644 index 0000000..a5c9ba8 --- /dev/null +++ b/doc/source/user/01_configurations.rst @@ -0,0 +1,68 @@ +Configuration examples +====================== + +Configuration location is ``${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg`` usually ``${XDG_CONFIG_HOME}`` is in ``${HOME}/.config/``. + + +Default configuration +--------------------- + +MPD_sima runs without explicit configuration as long as your MPD server is easy +to discover (``localhost:6600`` or exposed via environment variables ``MPD_HOST``/``MPD_PORT``). + +The default configuration is to run in *track mode* with suggestions from last.fm: + +.. code:: ini + + [MPD] + # Change MPD server here + #host = mpdserver.example.org + #port = 6600 + + [sima] + internal = Crop, Lastfm, Random + history_duration = 8 + queue_length = 2 + + [crop] + consume = 10 + + [lastfm] + queue_mode = track + single_album = False + track_to_add = 1 + +Album mode +^^^^^^^^^^ + +One of the first request added to MPD_sima was album mode. It allows to queue whole album instead of single tracks. + +Here the configuration keeps the queue plugin *Lastfm* but configure it to queue albums (``queue_mode = album``) and ask for 2 albums to be add. + +The configuration of MPD_sima in ``sima`` section is also modified for ``queue_length``. The value of 10 is to trigger album queueing when there are 10 tracks or less in the queue. + +.. code:: ini + + [MPD] + # Change MPD server here + #host = mpdserver.example.org + #port = 6600 + + [sima] + internal = Crop, Lastfm, Random + history_duration = 8 + queue_length = 10 + + [crop] + consume = 10 + + [lastfm] + queue_mode = album + album_to_add = 2 + + +Offline auto-queuing +-------------------- + + +.. vim: spell spelllang=en diff --git a/doc/source/user/10_metadata.rst b/doc/source/user/10_metadata.rst new file mode 100644 index 0000000..0a220b3 --- /dev/null +++ b/doc/source/user/10_metadata.rst @@ -0,0 +1,35 @@ +.. _metadata-convention: + +Music library metadata convention +================================= + +In order to choose which tracks to add, your music library needs to follow some +conventions regarding **metadata** [1]_. Files in your library should be tagged +with the metadata best describing the music file. + +Be aware that the benefit from a well tagged library goes far beyond the use of +MPD_sima alone. Any piece of software will take advantage of a well tagged +library, especially music players. If you already use MPD_ as a player, you are +already well aware of it. + +A minimal set of tags required for MPD_sima to work would be ``ARTIST``, ``ALBUM``, ``TITLE``, but in order to work properly and with all plugins a more complete tag set is recommended. + +MPD_sima is actually expecting: ``ARTIST``, ``ALBUM``, ``TITLE``, ``ALBUMARTIST``, +``GENRE`` and some MusicBrainzIDs_ [2]_ as well: ``MUSICBRAINZ_ARTISTID``, +``MUSICBRAINZ_ALBUMID`` and ``MUSICBRAINZ_ALBUMARTISTID``. + +There are very good tools to (auto)tag you music library, picard_ is highly +recommended, beets_ is also a good alternative. Actually any piece of software +tagging your files with the most common tags (albumartist especially) and +MusicBrainzIDs_ [3]_ should be fine. + + + +.. [1] commonly named tags or `ID3 tags`_ for MP3, but most audio format have some metadata features. + +.. [2] MusicBrainz_ provides a reliable and unambiguous form of music identification; this music identification is performed through the use of MusicBrainz Identifiers (MBIDs_). +.. [3] cf 2_ + +.. include:: ../links.rst + +.. vim: spell spelllang=en -- 2.39.2