review and update all documentation (#3)

.github/workflows/documentation.yml → .github/workflows/docs_build.yml

@@ -1,11 +1,6 @@
-name: 📃 Publish documentation
+name: 🏗️ Build documentation
 
 on:
-  push:
-    branches: [ master ]
-    paths:
-      - musify/**
-      - docs/**
   pull_request_target:
     branches: [ master ]
     paths:
@@ -14,7 +9,8 @@ on:
 
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+  workflow_call:
+
 permissions:
   contents: read
 
@@ -52,22 +48,3 @@ jobs:
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./docs/_build/html
-
-  deploy:
-    name: Deploy pages 🚀
-    runs-on: ubuntu-latest
-    needs: build
-    if: ${{ github.ref == 'refs/heads/master' && github.event_name != 'workflow_dispatch' }}
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    permissions:
-      pages: write
-      id-token: write
-    concurrency:
-      group: ${{ github.workflow }}
-      cancel-in-progress: false
-    steps:
-      - name: 🚀 Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

.github/workflows/docs_publish.yml

@@ -0,0 +1,32 @@
+name: 📃 Publish documentation
+
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - musify/**
+      - docs/**
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: 🏗️ Build
+    uses: ./.github/workflows/docs_build.yml
+
+  deploy:
+    name: 🚀 Deploy pages
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: 🚀 Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,12 +1,15 @@
 # Musify
 
-[![PyPI - Version](https://badge.fury.io/py/musify.svg)](https://badge.fury.io/py/musify)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/musify.svg)](https://pypi.org/project/musify/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/musify)](https://pypi.org/project/musify/)
-[![Contributors](https://img.shields.io/github/contributors/geo-martino/musify)](https://github.com/geo-martino/musify/graphs/contributors)
+[![PyPI Version](https://img.shields.io/pypi/v/musify?logo=pypi&label=Latest%20Version)](https://pypi.org/project/musify)
+[![Python Version](https://img.shields.io/pypi/pyversions/musify.svg?logo=python&label=Supported%20Python%20Versions)](https://pypi.org/project/musify/)
+</br>
+[![PyPI Downloads](https://img.shields.io/pypi/dm/musify?label=Downloads)](https://pypi.org/project/musify/)
+[![Code Size](https://img.shields.io/github/languages/code-size/geo-martino/musify?label=Code%20Size)](https://github.com/geo-martino/musify)
+[![Contributors](https://img.shields.io/github/contributors/geo-martino/musify?logo=github&label=Contributors)](https://github.com/geo-martino/musify/graphs/contributors)
+[![License](https://img.shields.io/github/license/geo-martino/musify?label=License)](https://github.com/geo-martino/musify/blob/master/LICENSE)
 </br>
 [![GitHub - Deployment](https://github.com/geo-martino/musify/actions/workflows/deploy.yml/badge.svg)](https://github.com/geo-martino/musify/actions/workflows/deploy.yml)
-[![GitHub - Documentation](https://github.com/geo-martino/musify/actions/workflows/documentation.yml/badge.svg)](https://github.com/geo-martino/musify/actions/workflows/documentation.yml)
+[![GitHub - Documentation](https://github.com/geo-martino/musify/actions/workflows/docs_deploy.yml/badge.svg)](https://github.com/geo-martino/musify/actions/workflows/docs_deploy.yml)
 
 ### A Swiss Army knife for music library management
 Supporting local and music streaming service (remote) libraries.
@@ -386,7 +389,7 @@ python -m pip install musify
 ## Currently Supported
 
 - **Music Streaming Services**: `Spotify`
-- **Audio filetypes**: `.mp3` `.m4a` `.wma` `.flac`
+- **Audio filetypes**: `.flac` `.m4a` `.wma` `.mp3`
 - **Local playlist filetypes**: `.m3u` `.xautopf`
 - **Local Libraries**: `MusicBee`
 

README.template.md

@@ -1,12 +1,15 @@
 # {program_name}
 
-[![PyPI - Version](https://badge.fury.io/py/{program_name_lower}.svg)](https://badge.fury.io/py/{program_name_lower})
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/{program_name_lower}.svg)](https://pypi.org/project/{program_name_lower}/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/{program_name_lower})](https://pypi.org/project/{program_name_lower}/)
-[![Contributors](https://img.shields.io/github/contributors/{program_owner_user}/{program_name_lower})](https://github.com/{program_owner_user}/{program_name_lower}/graphs/contributors)
+[![PyPI Version](https://img.shields.io/pypi/v/{program_name_lower}?logo=pypi&label=Latest%20Version)](https://pypi.org/project/{program_name_lower})
+[![Python Version](https://img.shields.io/pypi/pyversions/{program_name_lower}.svg?logo=python&label=Supported%20Python%20Versions)](https://pypi.org/project/{program_name_lower}/)
+</br>
+[![PyPI Downloads](https://img.shields.io/pypi/dm/{program_name_lower}?label=Downloads)](https://pypi.org/project/{program_name_lower}/)
+[![Code Size](https://img.shields.io/github/languages/code-size/{program_owner_user}/{program_name_lower}?label=Code%20Size)](https://github.com/geo-martino/musify)
+[![Contributors](https://img.shields.io/github/contributors/{program_owner_user}/{program_name_lower}?logo=github&label=Contributors)](https://github.com/{program_owner_user}/{program_name_lower}/graphs/contributors)
+[![License](https://img.shields.io/github/license/{program_owner_user}/{program_name_lower}?label=License)](https://github.com/geo-martino/musify/blob/master/LICENSE)
 </br>
 [![GitHub - Deployment](https://github.com/{program_owner_user}/{program_name_lower}/actions/workflows/deploy.yml/badge.svg)](https://github.com/{program_owner_user}/{program_name_lower}/actions/workflows/deploy.yml)
-[![GitHub - Documentation](https://github.com/{program_owner_user}/{program_name_lower}/actions/workflows/documentation.yml/badge.svg)](https://github.com/{program_owner_user}/{program_name_lower}/actions/workflows/documentation.yml)
+[![GitHub - Documentation](https://github.com/{program_owner_user}/{program_name_lower}/actions/workflows/docs_deploy.yml/badge.svg)](https://github.com/{program_owner_user}/{program_name_lower}/actions/workflows/docs_deploy.yml)
 
 ### A Swiss Army knife for music library management
 Supporting local and music streaming service (remote) libraries.

docs/_static/style.css

@@ -1,3 +1,3 @@
 .wy-nav-content {
-    max-width: 1200px !important;
-}
+    max-width: 80% !important;
+}

docs/_templates/autosummary/class.rst

@@ -6,7 +6,7 @@
     {%- if name.endswith(".exception") -%}
         {%- set name = "exceptions"-%}
     {%- else -%}
-        {%- set name = name.replace(project + ".", "").split(".") | last -%}
+        {%- set name = name.replace(project + ".", "").replace("_", " ").split(".") | last -%}
     {%- endif -%}
 
     {%- if name | lower in module_caps -%}

docs/_templates/autosummary/module.rst

@@ -6,7 +6,7 @@
     {%- if name.endswith(".exception") -%}
         {%- set name = "exceptions"-%}
     {%- else -%}
-        {%- set name = name.replace(project + ".", "").split(".") | last -%}
+        {%- set name = name.replace(project + ".", "").replace("_", " ").split(".") | last -%}
     {%- endif -%}
 
     {%- if name | lower in module_caps -%}

docs/_templates/module.rst_t

@@ -6,7 +6,7 @@
     {%- if name.endswith(".exception") -%}
         {%- set name = "exceptions"-%}
     {%- else -%}
-        {%- set name = name.replace("musify.", "").split(".") | last -%}
+        {%- set name = name.replace("musify.", "").replace("_", " ").split(".") | last -%}
     {%- endif -%}
 
     {%- if name | lower in module_caps -%}
@@ -26,4 +26,4 @@
 .. automodule:: {{ qualname }}
     {% for option in automodule_options -%}
         :{{ option }}:
-    {% endfor -%}
+    {% endfor -%}

docs/_templates/package.rst_t

@@ -6,7 +6,7 @@
     {%- if name.endswith(".exception") -%}
         {%- set name = "exceptions"-%}
     {%- else -%}
-        {%- set name = name.replace("musify.", "").split(".") | last -%}
+        {%- set name = name.replace("musify.", "").replace("_", " ").split(".") | last -%}
     {%- endif -%}
 
     {%- if name | lower in module_caps -%}

docs/conf.py

@@ -11,7 +11,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = MODULE_ROOT
-copyright = f'{datetime.now().year}, {PROGRAM_OWNER_NAME}'
+copyright = f"{datetime.now().year}, {PROGRAM_OWNER_NAME}"
 author = PROGRAM_OWNER_NAME
 release = __version__
 
@@ -20,31 +20,34 @@
 
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx_rtd_theme',
-    'sphinx.ext.graphviz',
-    'sphinx.ext.inheritance_diagram',
-    'autodocsumm',
+    "sphinx.ext.autodoc",
+    "sphinx_rtd_theme",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx_autodoc_typehints",
+    "autodocsumm",
 ]
-autodoc_member_order = 'bysource'
+autodoc_member_order = "bysource"
 autodoc_default_options = {
     "autosummary": True,
     "members": True,
     "undoc-members": False,
     "inherited-members": False,
     "special-members": False,
     "show-inheritance": True,
-    # "member-order": 'bysource',
+    # "member-order": "bysource",
 }
+typehints_defaults = "braces"
+typehints_use_rtype = False
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = ["_build"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_static_path = ['_static']
-html_theme = 'renku'
+html_static_path = ["_static"]
+html_theme = "renku"
 html_theme_options = dict(
     collapse_navigation=False,
     sticky_navigation=True,
@@ -53,7 +56,7 @@
     titles_only=False,
 )
 html_css_files = [
-    'style.css',
+    "style.css",
 ]
 html_context = dict(
     display_github=True,
@@ -64,8 +67,8 @@
 )
 
 # -- GraphViz configuration ----------------------------------
-graphviz_output_format = 'svg'
+graphviz_output_format = "svg"
 inheritance_graph_attrs = dict(rankdir="TB", size='""',
-                               fontsize=10, ratio='auto',
-                               center='true', style='solid')
-inheritance_node_attrs = dict(shape='ellipse', fontsize=10, fontname="monospace")
+                               fontsize=10, ratio="auto",
+                               center="true", style="solid")
+inheritance_node_attrs = dict(shape="ellipse", fontsize=10, fontname="monospace")

docs/index.rst

@@ -3,7 +3,7 @@ Welcome to Musify!
 
 .. toctree::
    :maxdepth: 2
-   :caption: 📖 Reference:
+   :caption: 📖 Reference
 
    musify.local
    musify.processors

musify/__init__.py

@@ -1,3 +1,5 @@
+"""Welcome to Musify"""
+
 from os.path import basename, dirname
 
 PROGRAM_NAME = "Musify"

musify/local/__init__.py

@@ -0,0 +1,3 @@
+"""
+Covers all local operations with local objects, files, tracks, albums, playlists, libraries etc.
+"""

musify/local/base.py

@@ -1,3 +1,7 @@
+"""
+Core abstract classes for the :py:mod:`Local` module.
+"""
+
 from abc import ABCMeta
 
 from musify.local.file import File

musify/local/collection.py

@@ -1,3 +1,7 @@
+"""
+Implements all collection types for a local library.
+"""
+
 from __future__ import annotations
 
 import logging
@@ -33,7 +37,6 @@ class LocalCollection[T: LocalTrack](ItemCollection[T], metaclass=ABCMeta):
     """
     Generic class for storing a collection of local tracks.
 
-    :ivar tag_sep: When representing a list of tags as a string, use this value as the separator.
     :param remote_wrangler: Optionally, provide a RemoteDataWrangler object for processing URIs on items.
         If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI.
     """
@@ -113,7 +116,9 @@ def __init__(self, remote_wrangler: RemoteDataWrangler = None):
         super().__init__()
 
         # noinspection PyTypeChecker
+        #: The :py:class:`MusifyLogger` for this  object
         self.logger: MusifyLogger = logging.getLogger(__name__)
+        #: A :py:class:`RemoteDataWrangler` object for processing URIs
         self.remote_wrangler = remote_wrangler
 
     def save_tracks(
@@ -225,8 +230,6 @@ class LocalCollectionFiltered[T: LocalItem](LocalCollection[T], metaclass=ABCMet
     Generic class for storing and filtering on a collection of local tracks
     with methods for enriching the attributes of this object from the attributes of the collection of tracks
 
-    :ivar tag_sep: When representing a list of tags as a string, use this value as the separator.
-
     :param tracks: A list of loaded tracks.
     :param name: The name of this collection.
         If given, the object only stores tracks that match the name given on the attribute of this object.
@@ -289,9 +292,7 @@ def _get_matching_tracks(self, tracks: Iterable[LocalTrack]) -> list[LocalTrack]
 
 class LocalFolder(LocalCollectionFiltered[LocalTrack], Folder[LocalTrack]):
     """
-    Object representing a collection of tracks in a folder on the local drive
-
-    :ivar tag_sep: When representing a list of tags as a string, use this value as the separator.
+    Object representing a collection of tracks in a folder on the local drive.
 
     :param tracks: A list of loaded tracks.
     :param name: The name of this folder.
@@ -332,18 +333,16 @@ def set_compilation_tags(self) -> None:
         Modify tags for tracks in the folders of this library.
 
         The following steps are applied to all non-compilation folders:
-
-        * Set compilation to False
+            * Set compilation to False
 
         The following steps are applied to all compilation folders:
-
-        * Set album name to folder name
-        * Set album artist to 'Various'
-        * Set track_number in ascending order by filename
-        * Set track_total to the number of tracks in the folder
-        * Set disc_number to 1
-        * Set disc_total to 1
-        * Set compilation to True
+            * Set album name to folder name
+            * Set album artist to 'Various'
+            * Set track_number in ascending order by filename
+            * Set track_total to the number of tracks in the folder
+            * Set disc_number to 1
+            * Set disc_total to 1
+            * Set compilation to True
         """
 
         count = 0
@@ -369,8 +368,6 @@ class LocalAlbum(LocalCollectionFiltered[LocalTrack], Album[LocalTrack]):
     """
     Object representing a collection of tracks of an album.
 
-    :ivar tag_sep: When representing a list of tags as a string, use this value as the separator.
-
     :param tracks: A list of loaded tracks.
     :param name: The name of this album.
         If given, the object only stores tracks that match the album ``name`` given.
@@ -453,8 +450,6 @@ class LocalArtist(LocalCollectionFiltered[LocalTrack], Artist[LocalTrack]):
     """
     Object representing a collection of tracks by a single artist.
 
-    :ivar tag_sep: When representing a list of tags as a string, use this value as the separator.
-
     :param tracks: A list of loaded tracks.
     :param name: The name of this artist.
         If given, the object only stores tracks that match the artist ``name`` given.
@@ -493,8 +488,6 @@ class LocalGenres(LocalCollectionFiltered[LocalTrack], Genre[LocalTrack]):
     """
     Object representing a collection of tracks within a genre.
 
-    :ivar tag_sep: When representing a list of tags as a string, use this value as the separator.
-
     :param tracks: A list of loaded tracks.
     :param name: The name of this genre.
         If given, the object only stores tracks that match the genre ``name`` given.