Merge pull request #69 from charite/develop

Creating version 0.11

.gitignore

@@ -1,3 +1,23 @@
 target
 dependency-reduced-pom.xml
-
+# Vim swap files
+*.sw?
+# gedit swap files
+*~
+# Eclipse stuff
+.classpath
+.project
+.settings
+# Coverity stuff
+cov-int*
+# Maven stuff
+*.iml
+# download directory
+/data*
+# any inline-generated VCF/Jannovar files
+*.jannovar
+*.vcf
+*.vcf.idx
+data
+# built manual
+manual/_build

LICENSE

@@ -0,0 +1,27 @@
+Jannovar is licenced under the BSD2 license.
+
+Copyright (c) 2013-2015, Charite Universitaetsmedizin Berlin
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README

@@ -0,0 +1,45 @@
+Building the Manual
+===================
+
+The manual is written using Sphinx [1] and hosted on ReadTheDocs [2]. We use
+the ReadTheDocs theme [3] for pretty HTML output.
+
+Prerequisites
+-------------
+
+You need to install the sphinx command in order to build the application. The
+most convenient way to do this is using the pip command in a virtualenv
+environment.  This section describes how to set this up.
+
+First, install virtualenv:
+
+    # sudo apt-get install virtualenv
+
+Then, create a virtualenv environment:
+
+    # virtualenv ~/local/virtualenv
+
+Enable this environment:
+
+     # . ~/local/virtualenv/bin/activate
+
+Now, you can use pip for installing the packages described in
+manual/requirements.txt into ~/local/virtualenv without affecting your global
+Python installation:
+
+    # pip install -r manual/requirements.txt
+
+Create HTML Pages
+-----------------
+
+Now, create the HTML pages. The results can be found in manual/_build/html
+
+    # cd manual
+    # make html
+
+Links
+-----
+
+[1] http://sphinx-doc.org/
+[2] https://readthedocs.org/
+[3] https://github.com/snide/sphinx_rtd_theme

README.md

@@ -1,95 +1,46 @@
 [![Build Status](https://travis-ci.org/charite/jannovar.svg?branch=master)](https://travis-ci.org/charite/jannovar)
-
+[![Documentation](https://travis-ci.org/charite/jannovar.svg?branch=master)](https://readthedocs.org/projects/pip/badge/?version=master)
 
 Jannovar
 ========
 
+Functional variant file annotation in Java. Jannovar provides a program for
+the annotation of VCF files and also exposes its functionality through a
+library API.
 
-Jannovar is a Java library and executable for annotating VCF files with
-gene/transcript-based annotations and performing simple pedigree/genotype
-filtering. If you are reading this, then preumably you have already
-downloaded the source code from github by using the command
-
-```
-$ git clone https://github.com/charite/jannovar
-```
-
-The source code of Jannovar is organized as a maven project
-that integrates the test and build phases. Here are the most important commands:
-
+Jannovar is licenced under the BSD2 license.
 
-* Compile all the Java classes
+More information is available in the [Jannovar
+manual](http://jannovar.readthedocs.org/).
 
-```
-$ cd jannovar
-$ mvn compile
-```
+Quickstart
+----------
 
-* Build a jar archive with all the classes but no Manifest for the main class
+Download binary files of the current release from our [GitHub release
+page](https://github.com/charite/jannovar/releases).
 
-```
-$ mvn jar:jar
-```
+After extracting the ZIP file, you can call Jannovar as follows.
 
-* Cause all of the test classes to be executed. It is also possible
-   to run the the cobertura test-coverage pluging. To do so, you need to
-   uncomment the corresponding lines in the pom.xml file. The results of
-   test coverage analysis will then be writtten to the
-   target/site/cobertura directory.
+Download the UCSC transcripts for hg19:
 
 ```
-$ mvn test
+# java -jar jannovar-cli-0.11.jar download hg19/ucsc
+[...]
 ```
 
-*  Generate javadoc and output it to the directory target/site/apidocs
+Annotate the example file `small.vcf`:
 
 ```
-$ mvn javadoc:javadoc
+# java -jar jannovar-cli-0.11.jar annotate data/hg19_ucsc.ser examples/small.vcf
+[...]
 ```
 
-* Create an executable Jar file the directory "target". This command
-   makes use of the shade:shade maven goal to package a Jar file that also
-   includes the Apache CLI library, i.e., it stands on its own. It does however
-   require that all of the test phase be performed as part of the
-   build.
+Inspect the resulting annotated file:
 
 ```
-$ mvn package
+# less small.jv.vcf
 ```
 
-Version
-=======
-
-Jannovar is currently at version 0.9-SNAPSHOT, meaning that we anticipate to extend the public API in the course of 2014 based on comments and suggestions from users. We do not anticipate deprecating or removing functions in the public API, but this cannot be entirely ruled out.
-
-License
-=======
-
-Jannovar is licenced under a BSD2 license.
-
-
-Copyright (c) 2013, Charite Universitätsmedizin Berlin
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-Redistributions of source code must retain the above copyright notice,
-this list of conditions and the following disclaimer.
-
-Redistributions in binary form must reproduce the above copyright
-notice, this list of conditions and the following disclaimer in the
-documentation and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+Also see the
+[Quickstart](http://jannovar.readthedocs.org/en/develop/quickstart.html) section
+in the Jannovar manual.

jannovar-cli/LICENSE

@@ -0,0 +1,27 @@
+Jannovar is licenced under the BSD2 license.
+
+Copyright (c) 2013-2015, Charite Universitaetsmedizin Berlin
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

jannovar-cli/README.md

@@ -0,0 +1,41 @@
+Jannovar
+========
+
+Functional variant file annotation in Java. Jannovar provides a program for
+the annotation of VCF files and also exposes its functionality through a
+library API.
+
+Jannovar is licenced under the BSD2 license.
+
+Resources:
+
+* [Homepage](http://charite.github.io/jannovar/)
+* [Manual](http://jannovar.readthedocs.org/)
+* [GitHub Page](https://github.com/charite/jannovar)
+
+Quickstart
+----------
+
+Download the UCSC transcripts for hg19:
+
+```
+# java -jar jannovar-cli-0.11.jar download hg19/ucsc
+[...]
+```
+
+Annotate the example file `small.vcf`:
+
+```
+# java -jar jannovar-cli-0.11.jar annotate data/hg19_ucsc.ser examples/small.vcf
+[...]
+```
+
+Inspect the resulting annotated file:
+
+```
+# less small.jv.vcf
+```
+
+Also see the
+[Quickstart](http://jannovar.readthedocs.org/en/develop/quickstart.html) section
+in the Jannovar manual.