johnwmillr · johnwmillr · Aug 31, 2020 · Aug 20, 2020 · Aug 20, 2020 · Aug 20, 2020
diff --git a/docs/Makefile b/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     = src
+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)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=src
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx==3.2.0
+sphinx-rtd-theme==0.5.0
diff --git a/docs/src/404.png b/docs/src/404.png
diff --git a/docs/src/404.rst b/docs/src/404.rst
@@ -0,0 +1,27 @@
+.. image:: 404.png
+
+
+Whoops!
+========
+The page you're looking for doesn't exist. Let's go
+:ref:`home <index>`.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Library
+
+   reference
+   release_notes
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Guide
+
+   setup
+   usage
+   contributing
+
+
+.. _Genius.com: https://www.genius.com
diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -0,0 +1,35 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'lyricsgenius'
+copyright = '2020, Allerter'
+author = 'Allerter'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx_rtd_theme',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.extlinks',
+]
+
+exclude_patterns = ['build']
+master_doc = 'index'
+autosummary_generate = True
+# -- Options for HTML output -------------------------------------------------
+
+highlight_language = 'python3'
+html_theme = 'sphinx_rtd_theme'
+
+# -- Other -------------------------------------------------------------------
+
+extlinks = {
+    'issue': ('https://github.com/johnwmillr/LyricsGenius/issues/%s', '#'),
+    'commit': ('https://github.com/johnwmillr/LyricsGenius/commit/%s', '')
+}
diff --git a/docs/src/contributing.rst b/docs/src/contributing.rst
@@ -0,0 +1,8 @@
+Contributing
+------------
+
+Please contribute! If you want to fix a bug, suggest improvements, or
+add new features to the project, just `open an issue`_ or send me a pull
+request.
+
+.. _open an issue: https://github.com/johnwmillr/LyricsGenius/issues
diff --git a/docs/src/examples/example projects.rst b/docs/src/examples/example projects.rst
@@ -0,0 +1,16 @@
+Example projects
+==================
+
+-  `Trucks and Beer: A textual analysis of popular country music`_
+-  `Neural machine translation: Explaining the Meaning Behind Lyrics`_
+-  `What makes some blink-182 songs more popular than others?`_
+-  `Sentiment analysis on hip-hop lyrics`_
+-  `Does Country Music Drink More Than Other Genres?`_
+-  `49 Years of Lyrics: Why So Angry?`_
+
+.. _`Trucks and Beer: A textual analysis of popular country music`: http://www.johnwmillr.com/trucks-and-beer/
+.. _`Neural machine translation: Explaining the Meaning Behind Lyrics`: https://github.com/tsandefer/dsi_capstone_3
+.. _What makes some blink-182 songs more popular than others?: http://jdaytn.com/posts/download-blink-182-data/
+.. _Sentiment analysis on hip-hop lyrics: https://github.com/Hugo-Nattagh/2017-Hip-Hop
+.. _Does Country Music Drink More Than Other Genres?: https://towardsdatascience.com/does-country-music-drink-more-than-other-genres-a21db901940b
+.. _`49 Years of Lyrics: Why So Angry?`: https://towardsdatascience.com/49-years-of-lyrics-why-so-angry-1adf0a3fa2b4
diff --git a/docs/src/examples/snippets.rst b/docs/src/examples/snippets.rst
@@ -0,0 +1,73 @@
+.. _snippets:
+
+Snippets
+==================
+Here are some snippets showcasing how the library can be used.
+
+
+- `All the songs of an artist`_
+- `Artist's least popular song`_
+- `YouTube URL of artist's songs`_
+- `Searching for a song by lyrics`_
+
+
+All the songs of an artist
+------------------------------
+
+.. code:: python
+
+    from lyricsgenius import Genius
+
+    genius = Genius(token)
+    genius.search_artist('Andy Shauf')
+    artist.save_lyrics()
+
+
+Artist's least popular song
+----------------------------
+.. code:: python
+
+    genius = Genius(token)
+
+    artist = genius.search_artist('Andy Shauf', max_songs=1)
+    page = 1
+    songs = []
+    while page:
+        request = genius.get_artist_songs(artist._id,
+                                          sort='popularity',
+                                          per_page=50,
+                                          page=page)
+        songs.extend(request['songs'])
+        page = request['next_page']
+    least_popular_song = genius.search_song(songs[-1]['title'], artist.name)
+    print(least_popular_song.lyrics)
+
+
+YouTube URL of artist's songs
+------------------------------
+.. code:: python
+
+    import json
+    # we have saved the songs with artist.save_lyrics() before this
+    with open('saved_file.json') as f:
+        data = json.load(f)
+    for song in data['songs']:
+        links = song['media']
+        if links:
+            for media in links:
+                if media['provider'] == 'youtube':
+                    print(print(['song'] + ': ' + media['url'])
+                    break
+
+
+Searching for a song by lyrics
+-------------------------------
+.. code:: python
+
+    from lyricsgenius import Genius
+
+    genius = Genius(token)
+
+    request = genius.search_genius_web('Jeremy can we talk a minute?')
+    for hit in request['sections'][2]['hits']:
+        print(hit['result']['name'])
diff --git a/docs/src/header.png b/docs/src/header.png
diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -0,0 +1,50 @@
+.. _index:
+.. image:: header.png
+
+
+LyricsGenius: a Python client for the Genius.com API
+====================================================
+
+.. |Build Status| image:: https://travis-ci.org/johnwmillr/LyricsGenius.svg?branch=master
+   :target: https://travis-ci.org/johnwmillr/LyricsGenius
+.. |PyPI version| image:: https://badge.fury.io/py/lyricsgenius.svg
+   :target: https://pypi.org/project/lyricsgenius/
+.. |Python version| image:: https://img.shields.io/badge/python-3.x-brightgreen.svg
+   :target: https://pypi.org/project/lyricsgenius/
+
+
+``lyricsgenius`` provides a simple interface to the song, artist, and
+lyrics data stored on `Genius.com`_.
+
+Using this library you can convienently access the content on Genius.com
+And much more using the public API.
+
+You can use ``pip`` to install lyricsgenius:
+
+.. code:: bash
+
+   pip install lyricsgenius
+
+
+But before using the library you will need to get an access token. Head over
+to :ref:`setup` to get started.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Library
+
+   reference
+   release_notes
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Guide
+
+   setup
+   usage
+   contributing
+
+
+.. _Genius.com: https://www.genius.com
diff --git a/docs/src/reference.rst b/docs/src/reference.rst
@@ -0,0 +1,25 @@
+.. _reference:
+
+=========
+Reference
+=========
+All public objects are documented in these sections.
+
+================== =============================
+:ref:`api`         API
+:ref:`Genius`      Genius
+:ref:`Artist`	   Artist object
+:ref:`Song`        Song object
+:ref:`utils`       Utility functions
+================== =============================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Index
+   :hidden:
+
+   reference/api
+   reference/genius
+   reference/artist
+   reference/song
+   reference/utils
diff --git a/docs/src/reference/api.rst b/docs/src/reference/api.rst
@@ -0,0 +1,17 @@
+.. _api:
+.. currentmodule:: lyricsgenius.api
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: API
+
+API
+=======================
+The :ref:`Genius` class inherits this class, and it's recommended to
+call the methods using the Genius calss rather than accessing this
+class directly.
+
+.. autoclass:: API
+   :members:
+   :member-order: bysource
+   :no-show-inheritance:
diff --git a/docs/src/reference/artist.rst b/docs/src/reference/artist.rst
@@ -0,0 +1,37 @@
+.. _artist:
+.. currentmodule:: lyricsgenius.artist
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Artist
+
+Artist
+=======================
+The Artist object which holds the details of the artist
+and the :ref:`song` objects of that artist.
+
+Properties
+-----------
+.. autosummary::
+   :nosignatures:
+
+   Artist.name
+   Artist.image_url
+   Artist.songs
+
+
+Methods
+--------
+.. autosummary::
+   :nosignatures:
+
+   Artist.add_song
+   Artist.to_json
+   Artist.to_text
+   Artist.save_lyrics
+
+.. autoclass:: lyricsgenius.artist.Artist
+    :members:
+    :exclude-members: get_song
+    :member-order: bysource
+    :no-show-inheritance:
diff --git a/docs/src/reference/genius.rst b/docs/src/reference/genius.rst
@@ -0,0 +1,35 @@
+.. _genius:
+.. currentmodule:: lyricsgenius.api
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Genius
+
+
+Genius
+=======================
+High-level interface to the API
+
+The Genius class provides a high-level interface to the Genius
+API that provides convenient to much more than the pure API
+offers, such as getting song lyrics.
+
+.. autosummary::
+   :nosignatures:
+
+   Genius.get_annotation
+   Genius.get_artist
+   Genius.get_artist_songs
+   Genius.get_referents
+   Genius.get_song
+   Genius.get_song_annotations
+   Genius.save_artists
+   Genius.search_artist
+   Genius.search_genius
+   Genius.search_genius_web
+   Genius.search_song
+
+.. autoclass:: lyricsgenius.api.Genius
+   :members:
+   :inherited-members:
+   :show-inheritance: