Add documentation

This adds documentation to the project.

Author: mimischi

.gitignore

@@ -10,6 +10,10 @@ dist/
 **/runtimes.csv
 **/runtimes.pdf
 
+# Documentation
+docs/_build/
+docs/.doctrees/
+
 # Ignore local Pipfile
 Pipfile
 Pipfile.lock

.travis.yml

@@ -24,6 +24,11 @@ matrix:
     - os: osx
       env: PYTHON_VERSION=2.7
 
+    - os: linux
+      env: PIP_DEPENDENCIES="sphinx-click"
+           MAIN_CMD="python setup.py build_sphinx"
+           SETUP_CMD=""
+
     - os: linux
       env: PIP_DEPENDENCIES="restructuredtext_lint"
            MAIN_CMD="rst-lint README.rst"

MANIFEST.in

@@ -1,5 +1,5 @@
 include README.rst
 include LICENSE
-include runtimes.png
 include AUTHORS
 include CHANGELOG.rst
+include docs/_static/runtimes.png

README.rst

@@ -14,6 +14,9 @@
 .. image:: https://travis-ci.org/bio-phys/MDBenchmark.svg?branch=master
     :target: https://travis-ci.org/bio-phys/MDBenchmark
 
+.. image:: https://readthedocs.org/projects/mdbenchmark/badge/?version=latest&style=flat
+    :target: https://mdbenchmark.readthedocs.io/en/latest/
+
 .. image:: https://codecov.io/gh/bio-phys/MDBenchmark/branch/master/graph/badge.svg
     :target: https://codecov.io/gh/bio-phys/MDBenchmark
 
@@ -32,166 +35,99 @@ resources. It tries to make it as easy as possible to set up systems on varying
 numbers of nodes and compare their performances to each other.
 
 You can also create a plot to get a quick overview of the possible performance
-(and also show of to your friends)! The plot below shows the performance of an
+(and also show of to your friends)! The plot below shows the performance of a
 molecular dynamics system on up to five nodes with and without GPUs.
 
-.. image:: https://raw.githubusercontent.com/bio-phys/MDBenchmark/master/runtimes.png
+.. image:: https://raw.githubusercontent.com/bio-phys/MDBenchmark/master/docs/_static/runtimes.png
 
 
 Installation
 ============
 
-You can install ``mdbenchmark`` via ``pip`` or ``conda``:
-
-.. code::
+You can install ``mdbenchmark`` via ``pip``, ``conda`` or ``pipenv``:
 
-    $ pip install mdbenchmark
+pip
+---
 
 .. code::
 
-    $ conda install -c conda-forge mdbenchmark
+   pip install mdbenchmark
 
-Usage with a virtual environments
----------------------------------
-
-We recommend to install the package inside a `conda environment`_. This can
-easily be done with ``conda``. The following commands create an environment
-called ``benchmark`` and then installs ``mdbenchmark`` and its dependencies.
+conda
+-----
 
 .. code::
 
-    $ conda create -n benchmark
-    $ conda install -n benchmark -c conda-forge mdsynthesis click mdbenchmark
+   conda install -c conda-forge mdbenchmark
 
-Before every usage of ``mdbenchmark``, you need to first activate the conda
-environment. After doing this once, you can use the tool for the whole duration
-of your shell session.
+pipenv
+------
 
 .. code::
 
-   $ source activate benchmark
-   # mdbenchmark should now be usable!
-   $ mdbenchmark
-   Usage: mdbenchmark [OPTIONS] COMMAND [ARGS]...
+   pipenv install mdbenchmark
+
+After installation MDBenchmark is accessible on your command-line via ``mdbenchmark``::
+
+  $ mdbenchmark
+  Usage: mdbenchmark [OPTIONS] COMMAND [ARGS]...
 
-     Generate and run benchmark jobs for GROMACS simulations.
+    Generate and run benchmark jobs for GROMACS simulations.
 
-   Options:
-     --version  Show the version and exit.
-     --help     Show this message and exit.
+  Options:
+    --version  Show the version and exit.
+    --help     Show this message and exit.
 
-   Commands:
-     analyze   analyze finished benchmark.
-     generate  Generate benchmark queuing jobs.
-     submit    Start benchmark simulations.
+  Commands:
+    analyze   analyze finished benchmark.
+    generate  Generate benchmark queuing jobs.
+    submit    Start benchmark simulations.
 
 Features
 ========
 
 - Generates benchmarks for GROMACS and NAMD simulations (contributions for other MD engines are welcome!).
 - Automatically detects the queuing system on your high-performance cluster and submits jobs accordingly.
 - Grabs performance from the output logs and creates a fancy plot.
-- Can benchmark systems either with or without GPUs.
-
-Usage
-=====
-
-After installation, the ``mdbenchmark`` command should be available to you
-globally. If you have installed the package in a virtual environment, make sure
-to activate that first!
-
-Benchmark generation for GROMACS
---------------------------------
-
-Assuming your TPR file is called ``protein.tpr`` and you want to run benchmarks
-with the module ``gromacs/5.1.4-plumed2.3`` on up to ten nodes, run the
-following command:
-
-.. code::
-
-    $ mdbenchmark generate --name protein --module gromacs/5.1.4-plumed2.3 --max-nodes 10
-
-To run benchmarks on GPUs simply add the ``--gpu`` flag:
-
-.. code::
-
-    $ mdbenchmark generate --name protein --module gromacs/5.1.4-plumed2.3 --max-nodes 10 --gpu
-
-You can also create benchmarks for different versions of GROMACS:
-
-.. code::
-
-    $ mdbenchmark generate --name protein --module gromacs/5.1.4-plumed2.3 --module gromacs/2016.4-plumed2.3 --max-nodes 10 --gpu
-
-
-Benchmark generation for NAMD
------------------------------
-
-**NAMD support is experimental.** If you encounter any problems or bugs, we
-would appreciate to `hear from you`_.
+- Benchmarks systems on CPUs and/or GPUs.
 
-Generating benchmarks for NAMD follows a similar process to GROMACS. Assuming
-the NAMD configuration file is called ``protein.namd``, you will also need the
-corresponding ``protein.pdb`` and ``protein.psf`` inside the same folder.
-**Warning:** Please be aware that all paths given in the ``protein.namd`` file
-must be absolute paths. This ensures that MDBenchmark does not destroy paths
-when copying files around during benchmark generation.
+Short usage reference
+=====================
 
-In analogy to the GROMACS setup, you can execute the following command to
-generate benchmarks for a module named ``namd/2.12``:
+The following shows a short usage reference for MDBenchmark. Please consult the
+`documentation`_ for a complete guide.
 
-.. code::
-
-    $ mdbenchmark generate --name protein --module namd/2.12 --max-nodes 10
-
-To run benchmarks on GPUs add the ``--gpu`` flag:
-
-.. code::
-
-    $ mdbenchmark generate --name protein --module namd/2.12-gpu --max-nodes 10 --gpu
-
-Be aware that you will need to specify NAMD modules when running GPU and non-GPU
-benchmarks! To work with GPUs, NAMD needs to be compiled separately and will be
-probably named differently on the host of your choice. Using the ``--gpu``
-option on non-GPU builds of NAMD may lead to poorer performance and erroneous
-results.
+Benchmark generation
+--------------------
 
-Usage with multiple modules
----------------------------
+Assuming you want to benchmark GROMACS version 2016.4 and your TPR file is
+called ``protein.tpr``, run the following command::
 
-It is possible to generate benchmarks for different MD engines with a single
-command:
+  mdbenchmark generate --name protein --module gromacs/2016.4
 
-.. code::
+To run benchmarks on GPUs simply add the ``--gpu`` flag::
 
-    $ mdbenchmark generate --name protein --module namd/2.12 --module gromacs/2016.3 --max-nodes 10
+  mdbenchmark generate --name protein --module gromacs/2016.4 --gpu
 
 Benchmark submission
 --------------------
 
-After you generated all benchmarks, you can submit them at once:
-
-.. code::
-
-    $ mdbenchmark submit
+After you generated your benchmarks, you can submit them at once::
 
-To start specific benchmarks separately, use the ``--directory`` option and
-specify the corresponding folder:
-
-.. code::
-
-    $ mdbenchmark submit --directory draco_gromacs/5.1.4-plumed2.3
+  mdbenchmark submit
 
 Benchmark analysis
 ------------------
 
-As soon as the benchmarks have been submitted you can run the analysis script
-via ``mdbenchmark analysis``. When at least one system has finished, the script
-will produce a ``.csv`` output file or a plot for direct usage (via the
-``--plot`` option).
+As soon as the benchmarks have been submitted you can run the analysis via
+``mdbenchmark analysis``. When at least one system has finished, the script will
+produce a ``.csv`` output file or a plot for direct usage (via the ``--plot``
+option).
 
 **Note:** The plotting function currently only allows to plot a CPU and GPU
-benchmark from the same module. We are working on fixing this. If you want to
+benchmark from the *same* module. This will be fixed in an upcoming version and
+is already implemented in the `develop
+<https://github.com/bio-phys/MDBenchmark/tree/develop>`_ branch. If you want to
 compare different modules with each other, either use the ``--directory`` option
 to generate separate plots or create your own plot from the provided CSV file.
 
@@ -206,84 +142,12 @@ to generate separate plots or create your own plot from the provided CSV file.
     4  gromacs/5.1.4-plumed2.3      5   51.71              15  False       draco     160
 
 
-Defining Host Templates
-=======================
-
-It is possible to define your own host templates in addition to the ones shipped
-with the package. A template file should have the same filename as the UNIX
-command ``hostname`` returns to be detected automatically. Otherwise you can
-point MDBenchmark to a specific template by providing its name via the
-``--host`` option.
-
-Assuming you created a new host template in your home directory ``~/.config/MDBenchmark/my_custom_hostfile``::
-
-    $ mdbenchmark generate protein --host my_custom_hostfile --module gromacs/5.1.4-plumed2.3
-
-Here is an example job template for the MPG cluster ``hydra``.
-
-.. code::
-
-    # @ shell=/bin/bash
-    #
-    # @ error = {{ name }}.err.$(jobid)
-    # @ output = {{ name }}.out.$(jobid)
-    # @ job_type = parallel
-    # @ node_usage = not_shared
-    # @ node = {{ n_nodes }}
-    # @ tasks_per_node = 20
-    {%- if gpu %}
-    # @ requirements = (Feature=="gpu")
-    {%- endif %}
-    # @ resources = ConsumableCpus(1)
-    # @ network.MPI = sn_all,not_shared,us
-    # @ wall_clock_limit = {{ formatted_time }}
-    # @ queue
-
-    module purge
-    module load {{ module }}
-
-    # run {{ module }} for {{ time }} minutes
-    poe gmx_mpi mdrun -deffnm {{ name }} -maxh {{ time / 60 }}
-
-MDBenchmark passes the following variables to each template:
-
-+----------------+---------------------------------------------------------------------+
-| Value          | Description                                                         |
-+================+=====================================================================+
-| name           | Name of the TPR file                                                |
-+----------------+---------------------------------------------------------------------+
-| gpu            | Boolean that is true, if GPUs are requested                         |
-+----------------+---------------------------------------------------------------------+
-| module         | Name of the module to load                                          |
-+----------------+---------------------------------------------------------------------+
-| n_nodes        | Maximal number of nodes to run on                                   |
-+----------------+---------------------------------------------------------------------+
-| time           | Benchmark run time in minutes                                       |
-+----------------+---------------------------------------------------------------------+
-| formatted_time | Run time for the queuing system in human readable format (HH:MM:SS) |
-+----------------+---------------------------------------------------------------------+
-
-To ensure correct termination of jobs ``formatted_time`` is 5 minutes longer
-than ``time``.
-
-MDBenchmark will look for user templates in the `xdg`_ config folders defined by
-the environment variables ``XDG_CONFIG_HOME`` and ``XDG_CONFIG_DIRS`` which by
-default are set to ``$HOME/.config/MDBenchmark`` and ``/etc/xdg/MDBenchmark``,
-respectively. If the variable ``MDBENCHMARK_TEMPLATES`` is set, the script will
-also search in that directory.
-
-MDBenchmark will first search in ``XDG_CONFIG_HOME`` and ``XDG_CONFIG_DIRS`` for
-a suitable template file. This means it is possible to overwrite system-wide
-installed templates or templates shipped with the package.
-
 Contributing
 ============
 
 Contributions to the project are welcome! Information on how to contribute to
 the project can be found in `CONTRIBUTING.md`_ and `DEVELOPER.rst`_.
 
-.. _conda environment: https://conda.io/docs/user-guide/tasks/manage-environments.html
-.. _hear from you: https://github.com/bio-phys/MDBenchmark/issues/new
-.. _xdg: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+.. _documentation: https://mdbenchmark.readthedocs.io/en/latest/
 .. _CONTRIBUTING.md: https://github.com/bio-phys/MDBenchmark/blob/master/.github/CONTRIBUTING.md
 .. _DEVELOPER.rst: https://github.com/bio-phys/MDBenchmark/blob/master/DEVELOPER.rst

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS      = --ignore .doctrees/environment.pickle
+SPHINXBUILD     = sphinx-build
+SPHINXAUTOBUILD = sphinx-autobuild
+SPHINXPROJ      = MDBenchmark
+SOURCEDIR       = .
+BUILDDIR        = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+build:
+	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+.PHONY: help build 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)

runtimes.png docs/_static/runtimes.pngruntimes.png renamed to docs/_static/runtimes.png

@@ -0,0 +1,18 @@
+<h2><a href="/">MDBenchmark documentation</a></h2>
+
+<p>
+  <iframe src="https://ghbtns.com/github-btn.html?user=bio-phys&repo=mdbenchmark&type=watch&count=true&size=large"
+    allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+<p>
+  <strong>MDBenchmark</strong> helps you to squeeze the maximum out of your
+  limited computing resources.
+</p>
+
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="http://github.com/bio-phys/mdbenchmark">MDBenchmark @ GitHub</a></li>
+  <li><a href="http://pypi.org/project/mdbenchmark">MDBenchmark @ PyPI</a></li>
+  <li><a href="http://github.com/bio-phys/mdbenchmark/issues">Issue Tracker</a></li>
+</ul>