Add a lot more documentation on how to use vixen.

docs/source/conf.py

@@ -14,6 +14,7 @@
 
 import sys
 import os
+from os.path import join
 
 # 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
@@ -56,9 +57,11 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.3'
-# The full version, including alpha/beta/rc tags.
-release = u'0.3'
+_d = {}
+fname = join(os.pardir, os.pardir, 'vixen', '__init__.py')
+exec(compile(open(fname).read(), fname, 'exec'), _d)
+version = release = _d['__version__']
+
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -110,7 +113,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/index.rst

@@ -19,4 +19,10 @@ minimally intrusive manner.
    installation
    using_vixen
 
+
+==================
+Indices and tables
+==================
+
+* :ref:`genindex`
 * :ref:`search`

docs/source/installation.rst

@@ -26,11 +26,16 @@ Dependencies
 Core dependencies
 ^^^^^^^^^^^^^^^^^^
 
-Please make sure you have a good, functional browser such as:
-- Mozilla Firefox (any recent version)
-- Google Chrome (any recent version)
+Please make sure you have a recent, functional browser such as:
+- Mozilla Firefox_ (any recent version)
+- Google Chrome_ (any recent version)
 - Internet Explorer (IE 9 and above)
 
+ViXeN is tested to work best on Firefox_ and Chrome_.
+
+.. _Firefox: https://www.mozilla.org/en-US/firefox/new/
+.. _Chrome: https://www.google.com/chrome/
+
 
 ^^^^^^^^^^^^^^^^^^^^^^
 Optional dependencies
@@ -43,7 +48,7 @@ The optional dependencies are:
 .. _ffmpeg: http://ffmpeg.org
 
 
-This is only needed if you wish to use ffmpeg to convert any of your video media.
+This is only needed if you wish to use ffmpeg_ to convert any of your video media.
 
 -------------------------------
 Installing ViXeN on GNU/Linux
@@ -66,17 +71,19 @@ More detailed instructions are given below.
 Using Nautilus
 ^^^^^^^^^^^^^^^^^^^
 
-1. Download the ViXen binary file (say vixen-0.5-linux64.tgz) from
+1. Download the ViXen binary file (say vixen-0.9-linux64.tgz) from
    `ViXeN binary`_ to your preferred directory.
 
-
 2. Right click and select 'Extract Here' or 'Open With Archive Manager'. A
    ViXeN folder will appear in the directory you have selected (in this case
    the folder will be ``vixen-0.5``).
 
-3. Open the directory and double click the ``vixen`` file. The ViXeN
-   application will open on the browser, **if** Nautilus supports running
-   executables. If it does not, run the command shown in :ref:`using-cli`.
+3. Open the directory and double click the ``ViXeN`` file (the file is
+   ``ViXeN.desktop``). The ViXeN application will open on the browser.
+
+4. If the above did not work you can try to run the ``vixen`` file. This will
+   run **if** Nautilus supports running executables. If it does not, run the
+   command shown in :ref:`using-cli`.
 
 .. _using-cli:
 
@@ -87,13 +94,13 @@ Using the Command Line
 After downloading and unpacking ViXen either :ref:`using-nautilus`, run the
 following commands on the terminal::
 
-	$ cd vixen-0.5
+	$ cd vixen-0.9
 
-Where ``vixen-0.5`` is the extracted ViXeN binary. Suppose you downloaded and
-unpacked the ``vixen-0.5-linux64.tgz`` file in a folder named ``Software`` in
+Where ``vixen-0.9`` is the extracted ViXeN binary. Suppose you downloaded and
+unpacked the ``vixen-0.9-linux64.tgz`` file in a folder named ``Software`` in
 your ``home`` directory, then this command will be::
 
-	$ cd Software/vixen-0.5
+	$ cd Software/vixen-0.9
 
 Then run the application using::
 
@@ -106,7 +113,7 @@ Installing ViXeN on Mac OS X
 
 1. On OS X, download the ZIP file.
 2. Unpack it.
-3. Run the resulting dmg file by double clicking it.
+3. Run the resulting ``ViXeN.dmg`` file by double clicking it.
 
 You may move this dmg file anywhere you like or move it to your
 ``Applications`` folder if you wish to.
@@ -122,3 +129,19 @@ Installing ViXeN on Windows
    shortcut that you can use to run the application.
 
 The application will open in your default browser window.
+
+-----------------
+Troubleshooting
+-----------------
+
+If the application fails to run or you have any problems, please look at the
+log file ``vixen.log`` located inside the ``.vixen`` folder in your home
+directory.
+
+- On Linux this is typically in the directory ``/home/username/.vixen``.
+- On OS X this is in ``/Users/username/.vixen``.
+- On Windows this may be ``C:\Users\username\.vixen``.
+
+Email your log file to the developers or the mailing list.
+
+The ViXeN mailing list is available at https://groups.google.com/forum/#!forum/vixen

docs/source/using_vixen.rst

@@ -4,30 +4,179 @@
 Using ViXeN
 =============
 
-When you first start the application it should open on the browser.
+This is a simple tutorial on how to get started using ViXeN and its features.
+
+When you first start the application it should open a new page on your default
+browser. If this is not a supported browser, you can simply copy the URL on
+the location bar onto a supported browser such as Chrome or Firefox and the UI
+should load correctly.
+
+When you first start you will have a rather empty page with an button on the
+left panel to create a new project.
+
 
 Setting up a project
 --------------------
 
-Adding tags
-^^^^^^^^^^^^
+Create a new project by clicking on "New project". Fill in the fields of the
+project on the right side.  The important fields to fill are:
+
+- Name: set this to a suitable name for your project.
+
+- Path: this is the path to the root of your media files that you wish to
+  index. Click on "Browse..." to choose the directory from a file browser. You
+  may also directly type the directory path on the text box. All files inside
+  this directory can be "indexed". You may choose to index only specific
+  extensions by adding specific extensions on the field below the "Tags" field.
+
+- Tags: this is a very important field. These define the various metadata tags
+  associated with your media. You may add as many fields as you desire. A tag
+  can be either a string, integer, float, or boolean. For each media file, you
+  will be able to change/edit these fields when viewing the project. You can
+  add multiple tags in one go by separating them with commas, for example:
+  fox, jackal, dog. Once added you can change the type of the tag on the UI.
+  You can add and remove tags later on also. One default tag is always added
+  called "completed" you may remove it without any loss of functionality if
+  you do not need it.
+
+- File extensions to index: this defaults to all extensions, you may specify
+  any extensions you specifically wish to index. For example specifying ".png,
+  .jpg" and clicking on the "Add extension" will index only the png and jpg
+  files. The button, "Find available extensions" will show you a list of all
+  extensions inside the specified path.
+
+- Processors: You may add a variety of processors that allow you to either
+  convert your media, copy your media, add tags using Python scripts, or use
+  an external program to add tags. This is discussed in greater detail in the
+  section :ref:`processing-media` below.  Processors are entirely optional.
+
+Once you have setup the project, simply click on "Apply changes" for ViXeN to
+quickly scan all the files and make its internal database. Depending on the
+size of your directory, this should take a few seconds. Once this is done, you
+can click on the "View" button on the left pane to view the media.
+
+If you do not want a project, you may simply click on the "Remove" button
+remove the project. This will remove only the internal metadata, your media
+will be untouched.
+
+Note that when the files are indexed the following tags are always available:
+
+- ctime: date: creation date/time of the file.
+- mtime: date: modified date/time of the file.
+- path: string: the full path of the file.
+- relpath: string: the relative path to the file with respect to the project root.
+- size: int: the file size in bytes.
+- type: string: the type of the file (video, audio, image, html, pdf, etc.)
 
 
 Viewing media
 --------------
 
+The view interface is very simple and divided into two parts. On the left side
+you will see a simple directory browser. Clicking on a directory (shown
+typically in bold with a trailing '/') will navigate into this directory and
+clicking on a file will display the media on the right side of the page. Below
+the directory browser, the metadata tags of the media file are shown. One may
+edit the tags as one sees fit.
+
+On the right side, the media file is shown. Any file format that the browser
+can render is typically shown currently this works for videos (webm, ogg
+theora video), image files ('.png', '.jpg', '.gif', '.svg' etc.), audio files
+('.mp3', '.m4a', '.ogg', etc.), HTML, text, and PDF. The rendering is really
+dependent on the browser and your platform.
+
+ViXeN thus makes it easy to view the data on the right and update the metadata
+for each file.
+
+.. note::
+
+   It is important to remember to save the project after changing the
+   metadata. This can be done by pressing the "Save" button or pressing
+   "Command+S" or "Control+S".
+
+While navigating the directory browser, there are a few useful keyboard
+shortcuts:
+
+- Pressing "h" or the left arrow key will go to the parent directory.
+- "k", "n", or the "down" arrow key will go to the next file,
+- "j", "p", or "up" arrow will go to the previous file/directory,
+- "l", "enter", or the right arrow key will either select/view the file or
+  navigate into a sub-directory.
+
+
 Searching
 -----------
 
+One powerful feature with ViXeN is the ability to search through the metadata.
 
-Exporting the tag information
-------------------------------
+By default searching for a string in the search box and pressing return/enter
+or pressing the search button will search for the occurrence of the string in
+the full path of the media file.
 
+To search for specific tags, let us consider an example project with the
+metadata tags "fox" (an integer), "jackal" (an integer), and "others"
+(string).
+
+- To find all the media which have a single fox, one types: ``fox:1``
+- To find all the media which greater than one fox, one types: ``fox:>1``
+- To find all the media which greater than one fox or one jackal, one types:
+  ``fox:>1 OR jackal:1``
+- To find all the media where the "others" tag has a gerbil one types:
+  ``others:gerbil``.
+- To find all the media where there is a gerbil and a single jackal one types:
+  ``jackal:1 AND others:gerbil``
+
+In addition, one may also search by the time of the media. Each media file's
+creation time (``ctime``) and modified time (``mtime``) are also indexed
+automatically.  One can search for the time as follows:
+
+- for all images modified in 2015: ``mtime:2015``,
+- for all images modified in 2015 January: ``mtime:201501`` or ``mtime:'jan
+  2015'``
+
+ViXeN uses whoosh_ to parse the query string. For more details on the query
+language see the `date parsing documentation
+<https://whoosh.readthedocs.io/en/latest/dates.html>`_.
+
+
+.. _whoosh: http://whoosh.readthedocs.io
+
+
+
+Exporting the tag information to a CSV file
+--------------------------------------------
+
+Once the tags have been entered one can export the metadata to a CSV file.
+Simply click on the "Export CSV" button and you will be prompted for a file.
+This file will contain all the tags for the data.
+
+
+Importing tag information from a CSV file
+------------------------------------------
+
+One may also import tag information from a CSV file. Click on the "Import CSV"
+button, supply a file and it will import the tags. The CSV file must have a
+"path" column which should be exactly the same path as the corresponding media
+file. If there is a doubt as to what path is stored by Vixen, export the
+project data to CSV and look at the path column.
+
+It is important to note that only tags that have already been defined in the
+project will be imported. The column name of the CSV file should match the tag
+name exactly. Any columns which do not have corresponding tags will not be
+imported.
+
+Finally, after importing the tags, one must save the project to have the
+changes be stored to disk.
+
+
+.. _processing-media:
 
 Processing media files
 ----------------------
 
-
+TBW.
 
 Advanced scripting
 -------------------
+
+TBW.