add howtos, contributing, release history to docs (#17)

.flake8

@@ -3,4 +3,5 @@ extend-exclude = .venv*
 extend-ignore = E266
 per-file-ignores =
     **/__init__.py:F401
-max-line-length = 120
+    docs/_howto/scripts/*:E402
+max-line-length = 120

.github/workflows/docs_build.yml

@@ -40,9 +40,7 @@ jobs:
 
       - name: 🏗️ Sphinx build
         run: |
-          make clean
-          sphinx-apidoc -o ./docs ./musify -d 4 --force --module-first --separate --no-toc -t ./docs/_templates
-          make html
+          make rebuild-html
 
       - name: 📦 Upload build artifacts
         uses: actions/upload-pages-artifact@v3

.github/workflows/docs_publish.yml

@@ -6,6 +6,8 @@ on:
     paths:
       - musify/**
       - docs/**
+  schedule:
+    - cron: '0 0 1 1 *'  # refresh copyright year on docs at least once every year
 
 concurrency:
   group: ${{ github.workflow }}

.gitignore

@@ -70,7 +70,6 @@ instance/
 
 # Sphinx/other documentation
 docs/_build/
-docs/modules.rst
 docs/musify*.rst
 .grip/
 

Makefile

@@ -7,11 +7,18 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = docs
 BUILDDIR      = docs/_build
+PROJECTNAME   = musify
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+rebuild-html: Makefile
+	$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm -f docs/"$(PROJECTNAME)"*.rst
+	sphinx-apidoc -o "$(SOURCEDIR)" ./"$(PROJECTNAME)" -d 4 --force --module-first --separate --no-toc -t "$(SOURCEDIR)"/_templates
+	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

README.md

@@ -25,17 +25,19 @@ Supporting local and music streaming service (remote) libraries.
 ## Contents
 
 * [Quick Guides](#quick-guides)
-  * [Spotify](#quick-guides-spotify)
-  * [Local](#quick-guides-local)
-  * [Sync local and remote](#quick-guides-sync)
-* [Currently Supported](#supported)
+  * [Spotify](#spotify)
+  * [Local](#local)
+* [Currently Supported](#currently-supported)
+* [Release History](#release-history)
+* [Contributing](#contributing)
 * [Motivation & Aims](#aims)
 * [Author Notes](#notes)
 
 > [!NOTE]  
 > This readme provides a brief overview of the program. 
 > [Read the docs](https://geo-martino.github.io/musify/) for full reference documentation.
 
+
 ## Installation
 Install through pip using one of the following commands:
 
@@ -46,19 +48,20 @@ pip install musify
 python -m pip install musify
 ```
 
-<a id="quick-guides"></a>
 ## Quick Guides
 
+These quick guides will help you get set up and going with Musify in just a few minutes.
+For more detailed guides, check out the [documentation](https://geo-martino.github.io/musify/)
+
 > [!TIP]
-> Set up logger to ensure you can see all info reported by the later operations.
+> Set up logging to ensure you can see all info reported by the later operations.
 > Libraries log info about loaded objects to the custom `STAT` level.
 > ```python
 > import logging
 > from musify.shared.logger import STAT
 > logging.basicConfig(format="%(message)s", level=STAT)
 > ```
 
-<a id="quick-guides-spotify"></a>
 ### Spotify
 
 > In this example, you will: 
@@ -166,7 +169,6 @@ python -m pip install musify
    library.log_sync(result)
    ```
 
-<a id="quick-guides-local"></a>
 ### Local
 
 > In this example, you will: 
@@ -215,7 +217,7 @@ python -m pip install musify
    playlist = library.playlists["<NAME OF YOUR PLAYLIST>"]  # case sensitive
    album = next(album for album in library.albums if album.name == "<ALBUM NAME>")
    artist = next(artist for artist in library.artists if artist.name == "<ARTIST NAME>")
-   folder = next(folder for folder in library.folders if folder.name == "<ALBUM NAME>")
+   folder = next(folder for folder in library.folders if folder.name == "<FOLDER NAME>")
    genre = next(genre for genre in library.genres if genre.name == "<GENRE NAME>")
    
    # pretty print information about the loaded objects
@@ -232,7 +234,7 @@ python -m pip install musify
    
    # get a track according to a specific tag
    track = next(track for track in library if track.artist == "<ARTIST NAME>")
-   track = next(track for track in library if "<GENRE>" in track.genres)
+   track = next(track for track in library if "<GENRE>" in (track.genres or []))
    
    # pretty print information about this track
    print(track)
@@ -294,105 +296,25 @@ python -m pip install musify
    print(result)
    ```
 
-<a id="quick-guides-sync"></a>
-### Sync data between local and remote libraries
+## Currently Supported
 
-> In this example, you will: 
-> - Search for local tracks on a music streaming service and assign unique remote IDs to tags in your local tracks
-> - Get tags and images for a track from a music stream service and save it them to your local track file
-> - Create remote playlists from your local playlists
+- **Music Streaming Services**: `Spotify`
+- **Audio filetypes**: `.mp3` `.flac` `.m4a` `.wma`
+- **Local playlist filetypes**: `.xautopf` `.m3u`
+- **Local Libraries**: `MusicBee`
 
-1. Set up and load at least one local library with a remote wrangler attached, and one remote API object.
-   > This guide will use Spotify, but any supported music streaming service can be used in generally the same way. 
-   > Just modify the imports as required.
-   ```python
-   from musify.local.library import LocalLibrary
-   from musify.spotify.api import SpotifyAPI
-   from musify.spotify.processors.wrangle import SpotifyDataWrangler
-   
-   local_library = LocalLibrary(
-       library_folders=["<PATH TO YOUR LIBRARY FOLDER>", ...],
-       playlist_folder="<PATH TO YOUR PLAYLIST FOLDER",
-       # this wrangler will be needed to interpret matched URIs as valid
-       remote_wrangler=SpotifyDataWrangler(), 
-   )
-   local_library.load()
-   
-   api = SpotifyAPI(
-       client_id="<YOUR CLIENT ID>",
-       client_secret="<YOUR CLIENT SECRET>",
-       scopes=[
-           "user-library-read",
-           "user-follow-read",
-           "playlist-read-collaborative",
-           "playlist-read-private",
-           "playlist-modify-public",
-           "playlist-modify-private"
-       ],
-   )
-   api.authorise()
-   ```
 
-2. Search for tracks and check the results:
-   ```python
-   from musify.spotify.processors.processors import SpotifyItemSearcher, SpotifyItemChecker
-   
-   albums = local_library.albums[:3]
-   
-   searcher = SpotifyItemSearcher(api=api)
-   searcher.search(albums)
-   
-   checker = SpotifyItemChecker(api=api)
-   checker.check(albums)
-   ```
+## Release History
 
-3. Load the matched tracks, get tags from the music streaming service, and save the tags to the file:
-   > **NOTE**: By default, URIs are saved to the {uri_tag} tag.
-   ```python
-   from musify.spotify.object import SpotifyTrack
-   
-   for album in albums:
-       for local_track in album:
-           remote_track = SpotifyTrack.load(local_track.uri, api=api)
-           
-           local_track.title = remote_track.title
-           local_track.artist = remote_track.artist
-           local_track.date = remote_track.date
-           local_track.genres = remote_track.genres
-           local_track.image_links = remote_track.image_links
-   
-           # alternatively, just merge all tags
-           local_track |= remote_track
-   
-           # save the track here or...
-           local_track.save(replace=True, dry_run=False)
-      
-       # ...save all tracks on the album at once here
-       album.save_tracks(replace=True, dry_run=False)
-   ```
-4. Once all tracks in a playlist have URIs assigned, sync the local playlist with a remote playlist:
-   ```python
-   from musify.spotify.library import SpotifyLibrary
-   
-   remote_library = SpotifyLibrary(api=api)
-   remote_library.load_playlists()
-   
-   local_playlist = local_library.playlists["<YOUR PLAYLIST'S NAME>"]  # case sensitive
-   remote_playlist = remote_library.playlists["<YOUR PLAYLIST'S NAME>"]  # case sensitive
-   
-   remote_playlist.sync(items=local_playlist, kind="new", reload=True, dry_run=False)
-   
-   # pretty print info about the reloaded remote playlist
-   print(remote_playlist)
-   ```
+For change and release history, 
+check out the [documentation](https://geo-martino.github.io/musify/release-history.html)
 
-<a id="supported"></a>
-## Currently Supported
 
-- **Music Streaming Services**: `Spotify`
-- **Audio filetypes**: `.flac` `.m4a` `.mp3` `.wma`
-- **Local playlist filetypes**: `.m3u` `.xautopf`
-- **Local Libraries**: `MusicBee`
+## Contributing
+
+For info on how to contribute to Musify, 
+check out the [documentation](https://geo-martino.github.io/musify/contributing.html)
+
 
 <a id="aims"></a>
 ## Motivations & Aims