add rst files to generate man page from

doc/commandline.rst

@@ -0,0 +1,23 @@
+====================
+COMMAND LINE OPTIONS
+====================
+COMMAND LINE OPTIONS
+--------------------
+-a, --add	add a new subscription (requires either --search, --channel or --playlist)
+-p playlist-id, --playlist=playlist-id	add a new playlist subscription (requires --add)
+--channel=channel	specify a channel for a new subscription (requires --add)
+-s search-parameter, --search=search-parameter	optionally add a search string to a new channel subscription or create a new search subscription (requires --add)
+--lssubs	list the currently available subscriptions
+--lsvids=subscription-id	print all videos from a subscription
+-u, --update	updates the information about the available videos
+-d, --download	download all available videos which haven't already been downloaded
+--catchup=subscription-id	mark all videos from one channel as read (requires subscription-id as argument)
+-r subscription-id, --remove=subscription-id	remove a subscription
+-c, --clean-database	clean the database of entries no longer listed in the current API response
+-l, --license	show the license of the program
+--version	show the currently running version number
+-q, --quiet	suppress all output
+-v, --verbose	be verbose and print also diagnostical messages
+-h, --help	show the help message and exit
+
+

doc/conf.py

@@ -41,7 +41,11 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'stov'
-copyright = u'2013, Helmut Pozimski'
+copyright = (u"2013, Helmut Pozimski License GPLv2, GNU GPL version 2 "
+		"<http://www.gnu.org/licenses/old-licenses/gpl-2.0> \n"
+		"This is free software: you are free to change and redistribute it. "
+		"There is NO WARRANTY, to the extent permitted by law.")
+
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -183,7 +187,8 @@ latex_elements = {
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'stov.tex', u'stov Documentation',
+  ('index', 'stov.tex', u"""a tool to subscribe to channels and users from"
+	" youtube and download the videos automatically""",
    u'Helmut Pozimski', 'manual'),
 ]
 
@@ -213,7 +218,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'stov', u'stov Documentation',
+    ('index', 'stov', (u"a tool to subscribe to channels and users from"
+	" youtube and download the videos automatically"),
      [u'Helmut Pozimski'], 1)
 ]
 

doc/configuration.rst

@@ -0,0 +1,42 @@
+=============
+CONFIGURATION
+=============
+CONFIGURATION
+-------------
+
+MAILTO:	recipient address used for notitifications
+
+MAILFROM:	sender address used for notifications
+
+MAILHOST:	host name or ip address of the mail server which is used to send notifications
+
+AUTH_NEEDED:	define if the smtp server need authentication (yes or no)
+
+USER_NAME:	user name to use for smtp authentication if defined
+
+PASSWORD:	password to use for SMTP authentication
+
+YOUTUBE-DL:	path to the youtube-dl binary if not found automatically
+
+DOWNLOADDIR:	path the downloaded videos are saved into
+
+DATABASE:	file name to use for the database
+
+SMTPPORT:	port used to connect to the mail server
+
+MAXVIDEOS:	maximum number of videos to retrieve from the youtube API for each subscription, default 25, maximum 50, reduce this parameter for better parsing performance
+
+NOTIFY:	define if you want to be notified via email about new episodes of your subscriptions, valid values: yes or no
+
+DB_VERSION:	database version (Do not change!)
+
+CONFIG_VERSION:	configuration version (Do not change!)
+
+VIDEOCODEC:	video codec used for downloaded videos (valid values: h264, webm or flv)
+
+MAXRESOLUTION:	maximum resolution to use for downloaded videos, please note that not all codecs and resolutions might be available so a lower resolution or other codec might be used in these cases
+
+MAXFAILS: 	number of times the download of a video may fail until it is marked as failed and won't be tried again
+
+CHECK_TITLE:	define if stov should check the title of each video in a search or channel with search string subscription. This works around some deficits of the youtube API which sometimes also returns video completely unrelated to your search. Videos whose titles don't match the search string will be entirely ignored. valid values: yes or no
+

doc/description.rst

@@ -0,0 +1,9 @@
+===========
+DESCRIPTION
+===========
+DESCRIPTION
+-----------
+
+Stov is a little tool which allows you to subscribe to channels (or search results within channels), playlists or search results on the video plattform youtube. It then pulls all necessary data from the youtube API and saves it into it's internal database. This information can be used to automatically download videos contained in the defined subscriptions. For this functionality, the additional *youtube-dl* utility is needed. It is recommended that you use cron or another similiar mechanism to periodically update video data and download new videos.
+
+Since stov only uses read-only access to the youtube API, no developer key or youtube account is needed to use it. 

doc/examples.rst

@@ -0,0 +1,14 @@
+========
+EXAMPLES
+========
+EXAMPLES
+--------
+
+**stov** --add --channel Gronkh --search 'Let's Play Minecraft'
+	subscribe to all videos in channel "Gronkh", containing "Let's Play Minecraft"
+**stov** -u
+	update all currently configured subscriptions
+**stov** --download
+	download all new available videos
+**stov** --lsvids 5
+	list all videos in the subscription with id 5

doc/files.rst

@@ -0,0 +1,10 @@
+=====
+FILES
+=====
+FILES
+-----
+
+**~/.stov/stov.config**
+	This file is automatically created when you run stov for the first time, optionally you may also use a rudamentary assistent which will ask you which value you'd like to use for each setting. See *CONFIGURATION* for more details.
+**~/.stov/stov.sqlite**
+	This database contains two tables ("videos" and "subscriptions") which contain all relevant information about the configured subscriptions and the videos contained in these. It uses sqlite3 format so you could also use sqlite3 on the command line to edit it manually if you feel the need to do so.

doc/index.rst

@@ -3,20 +3,13 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to stov's documentation!
-================================
-
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   synopsis
+   description
+   commandline
+   examples
+   configuration
+   files
+   seealso

doc/seealso.rst

@@ -0,0 +1,7 @@
+========
+SEE ALSO
+========
+SEE ALSO
+--------
+
+**youtube-dl**, get it from http://rg3.github.io/youtube-dl/

doc/synopsis.rst

@@ -0,0 +1,9 @@
+=========
+SYNOPSIS
+=========
+SYNOPSIS
+---------
+
+| **stov** [ **-a**/**--add** ] [ **-p**/**--playlist** playlist-id ] [ **--channel** channel-name ] [ **-s**/**--search** search-parameter ] [ **--lssubs** ] [ **--lsvids** subscription_id ]
+| [ **-u**/**--update** ] [ **-d**/**--download** ] [ **--catchup** ]  [ **-r**/**--remove** subscription-id ] [ **-c**/**-clean-database** ] [ **-l**/**--license** ] [ **--version** ] [ **-q**/**--quiet** ]
+| [ **-h**/**--help** ]