Sphinx Docs (#5)

* add sphinx docs

* requirements

.gitignore

@@ -9,3 +9,4 @@ data
 *.sqlite3
 instance
 .DS_Store
+docs/build

Makefile

@@ -13,6 +13,11 @@ init-db:
 tests:
 	python -m unittest discover -s tests;
 
+docs:
+	sphinx-apidoc ./src -o docs/source -M;
+	cd docs && make clean && make html && cd ..;
+	open docs/build/html/index.html;
+
 start:
 	uwsgi wsgi.ini
 

README.md

@@ -71,7 +71,7 @@ The calls supported so far are:
 
 ## Web Interface
 
-![web-ui](screenshot.png)
+![web-ui](https://raw.githubusercontent.com/ericdaat/webradio-to-spotify/master/screenshot.png)
 
 ## Contribute
 

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     = source
+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)

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=source
+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

docs/source/conf.py

@@ -0,0 +1,63 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Webradio to Spotify'
+copyright = '2019, Eric Daoud'
+author = 'Eric Daoud'
+
+# The full version, including alpha/beta/rc tags
+release = '2.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'm2r'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,19 @@
+.. Webradio to Spotify documentation master file, created by
+   sphinx-quickstart on Sat Jul 13 12:09:41 2019.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. mdinclude:: ../../README.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules.rst
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/modules.rst

@@ -0,0 +1,7 @@
+src
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   src

docs/source/src.application.rst

@@ -0,0 +1,43 @@
+src.application package
+=======================
+
+.. automodule:: src.application
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+src.application.api module
+--------------------------
+
+.. automodule:: src.application.api
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.application.auth module
+---------------------------
+
+.. automodule:: src.application.auth
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.application.web module
+--------------------------
+
+.. automodule:: src.application.web
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.application.wsgi module
+---------------------------
+
+.. automodule:: src.application.wsgi
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

docs/source/src.rst

@@ -0,0 +1,50 @@
+src package
+===========
+
+.. automodule:: src
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+
+   src.application
+
+Submodules
+----------
+
+src.db module
+-------------
+
+.. automodule:: src.db
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.playlist\_updater module
+----------------------------
+
+.. automodule:: src.playlist_updater
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.scraping module
+-------------------
+
+.. automodule:: src.scraping
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+src.spotify module
+------------------
+
+.. automodule:: src.spotify
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

requirements.txt

@@ -1,30 +1,52 @@
+alabaster==0.7.12
 autopep8==1.4.4
+Babel==2.7.0
 beautifulsoup4==4.7.1
 bs4==0.0.1
 certifi==2019.6.16
 chardet==3.0.4
 Click==7.0
+doc8==0.8.0
+docutils==0.14
 entrypoints==0.3
 flake8==3.7.8
 Flask==1.1.1
 idna==2.8
+imagesize==1.1.0
 itsdangerous==1.1.0
 Jinja2==2.10.1
 lxml==4.3.4
+m2r==0.2.1
 MarkupSafe==1.1.1
 mccabe==0.6.1
+mistune==0.8.4
 numpy==1.16.4
+packaging==19.0
 pandas==0.24.2
+pbr==5.4.0
 pycodestyle==2.5.0
 pyflakes==2.1.1
+Pygments==2.4.2
+pyparsing==2.4.0
 python-dateutil==2.8.0
 pytz==2019.1
 requests==2.22.0
+restructuredtext-lint==1.3.0
 selenium==3.141.0
 six==1.12.0
+snowballstemmer==1.9.0
 soupsieve==1.9.2
+Sphinx==2.1.2
+sphinx-rtd-theme==0.4.3
+sphinxcontrib-applehelp==1.0.1
+sphinxcontrib-devhelp==1.0.1
+sphinxcontrib-htmlhelp==1.0.2
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.2
+sphinxcontrib-serializinghtml==1.1.3
 spotipy==2.4.4
 SQLAlchemy==1.3.5
+stevedore==1.30.1
 urllib3==1.25.3
 uWSGI==2.0.18
 Werkzeug==0.15.4

src/application/wsgi.py

@@ -1,3 +1,6 @@
 from src.application import create_app
 
 application = create_app()
+
+if __name__ == "__main__":
+    application.run()

src/scraping.py

@@ -6,35 +6,35 @@
 - Call for `super()` in its constructor, and pass it the URL of the webpage\
     to crawl and the `playlist_id` to upload the songs to. e.g:
 
-    ```python
-    player_url = 'https://radio.com/awesome-song-history'
-    playlist_id = '3BCcE8T945z1MnfPWkFsfX'
-    super(YourScrapper, self).__init__(player_url, playlist_id)
-    ```
+    .. code-block:: python
+
+        player_url = 'https://radio.com/awesome-song-history'
+        playlist_id = '3BCcE8T945z1MnfPWkFsfX'
+        super(YourScrapper, self).__init__(player_url, playlist_id)
 
 - Overide the `get_song_history` method, the first row should be:
 
-    ```python
-    soup, driver = self.scrap_webpage()
-    ```
+    .. code-block:: python
+
+        soup, driver = self.scrap_webpage()
 
 - Add your scraper in the [tests](./tests/test_scraping.py) folder:
 
-    ```python
-    class TestYourScraper(GenericScraperTest):
-        scraper = scraping.YourScraper()
-    ```
+    .. code-block:: python
+
+        class TestYourScraper(GenericScraperTest):
+            scraper = scraping.YourScraper()
 
 - Add your scraper in the
   [src.playlist_updater.Updater](./src/playlist_updater.py) class:
 
-    ```python
-    self.scrapers = [
-        scraping.KSHEScraper(),
-        scraping.EagleScraper(),
-        scraping.YourScraper()  # New scraper!
-    ]
-    ```
+    .. code-block:: python
+
+        self.scrapers = [
+            scraping.KSHEScraper(),
+            scraping.EagleScraper(),
+            scraping.YourScraper()  # New scraper!
+        ]
 
 - You're all set!
 """