Merge pull request #14 from Dr-Blank/13-update-all-docstrings

Improve Docs for the Module

.vscode/tasks.json

@@ -62,6 +62,16 @@
         "kind": "build",
         "isDefault": false
       }
+    },
+    // build docs "sphinx-build . _build"
+    {
+      "label": "docs",
+      "type": "shell",
+      "command": "poetry run sphinx-build docs/ docs/_build",
+      "group": {
+        "kind": "build",
+        "isDefault": false
+      }
     }
   ]
 }

docs/conf.py

@@ -6,23 +6,32 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'lrclibapi'
-copyright = '2023, Dr-Blank'
-author = 'Dr-Blank'
-release = '0.0.1'
+from importlib.metadata import version
+
+_python_project_name = "lrclibapi"
+project = "LRCLib Python API"
+copyright = "2023, Dr-Blank"
+author = "Dr-Blank"
+release = version(_python_project_name)
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
-
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+extensions = [
+    "sphinx.ext.autodoc",  # to generate the docs from the docstrings
+    "sphinx.ext.todo",  # to document the todos
+    "sphinx.ext.viewcode",  # to generate the source code
+    "sphinx.ext.autosectionlabel",  # to reference the sections with their titles
+    "sphinx.ext.napoleon",  # to support the Google and NumPy docstrings
+    "nbsphinx",  # to support the Jupyter notebooks
+]
 
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/examples/fetch_lyrics.ipynb

@@ -0,0 +1,162 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# 📥Fetching lyrics using the API\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "install dependencies\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install lrclibapi\n",
+    "from IPython.display import clear_output\n",
+    "clear_output()\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initialize the API\n",
+    "\n",
+    "using the `user_agent` is recommended by the API documentation\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[00:17.12] I feel your breath upon my neck\n",
+      "[00:20.41] A soft caress as cold as death\n",
+      "[00:29.60] I didn't know you well back then\n",
+      "[00:32.82] I blame it all on luck and vain\n",
+      "[00:41.37] Your blood like wine, I wanted in\n"
+     ]
+    }
+   ],
+   "source": [
+    "from lrclib import LrcLibAPI\n",
+    "\n",
+    "# Create an instance of the API\n",
+    "api = LrcLibAPI(user_agent=\"my-app/0.0.1\")\n",
+    "\n",
+    "# Get lyrics for a track\n",
+    "lyrics = api.get_lyrics(\n",
+    "    track_name=\"I Want to Live\",\n",
+    "    artist_name=\"Borislav Slavov\",\n",
+    "    album_name=\"Baldur's Gate 3 (Original Game Soundtrack)\",\n",
+    "    duration=233,\n",
+    ")\n",
+    "\n",
+    "found_lyrics = lyrics.synced_lyrics or lyrics.plain_lyrics\n",
+    "print(\"\\n\".join(found_lyrics.split(\"\\n\")[:5]))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Don't know exactly what to search for?\n",
+    "\n",
+    "Use the search endpoint\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Exile - I Don't Want To Be A Memory (Live At Billy Bob's Texas)\n",
+      "Don Williams - I Wouldn't Want To Live If You Didn't Love Me (Volume Three)\n",
+      "Don Williams - I Wouldn't Want To Live If You Didn't Love Me (The Definitive Collection)\n",
+      "Ben Harper - I Want To Be Ready (The Will To Live)\n",
+      "Ben Harper - I Want to Be Ready (The Will to Live)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Search for a lyrics\n",
+    "results = api.search_lyrics(\n",
+    "    track_name=\"I Want to Live\",\n",
+    ")\n",
+    "\n",
+    "# Print the results\n",
+    "for result in results[:5]:\n",
+    "    print(f\"{result.artist_name} - {result.track_name} ({result.album_name})\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Fetch lyrics for a song using id\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[00:06.98] I don't want to be a memory\n",
+      "[00:11.59] Just a shadow in your mind\n",
+      "[00:15.25] Wanna be the one you always need\n",
+      "[00:19.85] Not the one you left behind\n",
+      "[00:23.54] I don't want to be a notch in your handle\n"
+     ]
+    }
+   ],
+   "source": [
+    "lyrics = api.get_lyrics_by_id(results[0].id)\n",
+    "\n",
+    "found_lyrics = lyrics.synced_lyrics or lyrics.plain_lyrics\n",
+    "print(\"\\n\".join(found_lyrics.split(\"\\n\")[:5]))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.0b1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/examples/index.rst

@@ -0,0 +1,13 @@
+📝Examples
+===========
+
+This section contains examples of how to use the module.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   fetch_lyrics
+
+.. todo::
+   Add more examples

docs/index.rst

@@ -3,11 +3,21 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to lrclib's documentation!
-==================================
+.. meta::
+   :description: Python library which implements API to download lyrics from
+                   lrclib.net.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :hidden:
 
-   lrclib
+   modules
+   examples/index
+
+
+Welcome to LRCLib Python API documentation!
+===========================================
+
+Start with the :doc:`examples/index` page to see how to use the library or go
+directly to the :doc:`API Reference <modules>` of the library.