Merge pull request #117 from HECBioSim/docs

Docs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = Longbow
+SOURCEDIR     = .
+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/_static/table-overflow.css

@@ -0,0 +1,3 @@
+.wy-table-responsive table td {
+white-space: normal;
+}

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -0,0 +1,160 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain 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('../longbow'))
+
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'Longbow'
+copyright = u'2018, James T. Gebbie-Rayet, Gareth B. Shannon, Charles A. Laughton'
+author = u'James T. Gebbie-Rayet, Gareth B. Shannon, Charles A. Laughton'
+
+# The short X.Y version
+version = u''
+# The full version, including alpha/beta/rc tags
+release = u''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# 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 = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- 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'
+
+# 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
+# documentation.
+#
+# html_theme_options = {}
+
+# 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Longbowdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Longbow.tex', u'Longbow Documentation',
+     u'James T. Gebbie-Rayet, Gareth B. Shannon, Charles A. Laughton', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'longbow', u'Longbow Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Longbow', u'Longbow Documentation',
+     author, 'Longbow', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+def setup(app):
+    app.add_stylesheet('table-overflow.css')

docs/dev-contributing.rst

@@ -0,0 +1,14 @@
+Contributing
+************
+
+Contributions to Longbow are very welcome. To prevent things from becoming unwieldy for those of us that have to support the code base long-term we ask just a few things of our contributors.
+
+The first step in contributing is to clone the Longbow repository and then create a branch where you will work on your code/doc contribution. Please try to limit changes to one specific or set of related changes per branch, this way you can name your branch with something meaningful. If there is an existing issue in the github tracker covering your contribution, please name your branch with the issue number.
+
+Once you have written your code change, then please modify the documentation both in the source code and in the user documentation to reflect your changes. You should also update the unit tests or add more to test your changes. We have sections of this documentation detailing how to do local docs and test builds so that you can get these working before pusing back to github.
+
+You should make sure you add your name to the contributors section of the AUTHORS.rst file.
+
+Then push your branch back to our repository and open a pull request for merger, your code will then be reviewed by us and if everything above checks out and your feature is in the interest of our userbase then it will be merged for the next release.
+
+That is all there is to it. If you are unsure about your idea, then please do contact us either through the issue tracker or via email and we will be happy to discuss it with you.

docs/dev-documenting.rst

@@ -0,0 +1,25 @@
+Documenting
+***********
+
+Developers wishing to add to/modify existing features of Longbow are responsible for documenting them. As is similar with missing unit tests, pull requests that arrive with an absence of documentation for the addition/modification will be rejected upon review. The Longbow project should have good documentation both at a source code level and in the written documentation that goes out to users. The Longbow project is using Sphinx to compile its documentation, you will need to get some tools installed and try out building the documentation yourself locally before adding to them. The following process will show you how to achieve this:
+
+**1. Install the required packages**
+
+Before you can start documenting, you'll need some packages. So install these if you haven't already::
+
+    pip install --user sphinx sphinx-autobuild sphinx_rtd_theme
+
+
+**2. Try and make the documentation**
+
+The next step is to see if you can build the documentation html from the source. So change into the "docs" directory inside the Longbow source directory and run::
+
+    make html
+
+If everything has gone to plan then you should be able to now view the documentation in your web browser by navigating to the index.html file inside the "_build/html" directory.
+
+Adding to the documentation is easy, each page in the documentation has a .rst file associated with it. So to add documentation to an existing page then simply modify the relevant .rst file, if you are unsure which .rst file belongs to which page, then you can find out by looking at the index.rst table of contents and the titles at the top of each .rst file.
+
+The documentation simply uses reStructuredText format, not all features that are available in the reStructuredText will be available through Sphinx so it is best to use the Sphinx documentation for the reST format than the actual reST format documentation. This can be found at http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+
+happy documenting!

docs/dev-integrating.rst

@@ -0,0 +1,56 @@
+Integrating Longbow
+*******************
+
+Perhaps one of the most useful features of Longbow is the ease in which it can be utilised in other software. Longbow has been successfully applied in a range of other software products that require jobs to be offloaded onto high performance computing systems. 
+
+There are a number of ways in which Longbow can be integrated into other software, and which method should be used is largely dependant on how Longbow is going to be utilised. The following sections will introduce some of the most popular ways to integrate Longbow into other software and some of the use cases that each method should apply to.
+
+Wrapping the Application
+========================
+
+The quickest and most stable way to integrate Longbow into another application is to wrap the executable itself. This is the most stable way to integrate Longbow when considered from a code change perspective, since it is unlikely that the way the executable is called will change, even if the API changes considerably.
+
+This method is extremely useful for use in scripts, where the user might wish to make use of the power of Longbow to launch jobs after some automated setup. This does not mean that this is unsuitable for integration within applications, however, there are a number of considerations that should be made before choosing this method:
+
+1. Configuration - you will need to provide a configuration file with at least the details of the HPC machines and some job defaults. This is useful in cases where a very loose level of integration is required, for example if these settings are not collected as part of the application that is being integrated with Longbow. If these parameters are intended to be collected (say in a GUI) then you would have to write out configuration files to pass any parameters you wish to change that are not available for configuration via the Longbow command-line.
+
+2. Exceptions - exceptions will be difficult to deal with in this way of integrating, what will happen is that Longbow will handle its exceptions internally and the executable will exit should an error occur that Longbow can't handle by itself, this means that exceptions won't percolate up from Longbow and into your application. This will create an extra layer of complications when trying to deal with errors.
+
+3. Logging - when linking the executable you will end up creating a log file by default either in the user home directory or inside the directory that Longbow is launched from. The only way you can capture the logging output is to turn on the logging to stdout and capture this output, on which you will likely need to some form of processing on to get this into a form you want. This means that you have very little control over the logging that comes out of Longbow.
+
+The best way to start learning to use Longbow for an integration is to start using it, the following examples will show how to call the Longbow application in scripts. Before you can do these examples, you should complete the following prerequisites:
+
+* Longbow should be installed as an application on the machine that the script/application subject to the integration is installed upon.
+
+* Longbow should be configured with at least 1 HPC resource, it should be verified that you can run at least one of the examples.
+
+**A Simple Python Script**
+
+This example will highlight the simplest example of calling and capturing the output of Longbow in a python script::
+
+    #!/usr/bin/env python
+
+    import subprocess
+
+    # Format a call to python subprocess. Here we are using a non-shell call so
+    # the executable is in the format of a list, the first entry in the list should
+    # be the longbow executable and the second entry the arguments to Longbow. We
+    # are also piping stdout so we can capture the output.
+    inst = subprocess.Popen(["longbow", "--help"], stdout=subprocess.PIPE)
+
+    # Loop until the pipe is closed
+    while inst.poll() is None:
+
+        # Extract each line.
+        line = inst.stdout.readline()
+
+        # Output to the console, strip added newline chars.
+        print line.rstrip() 
+
+Integration by API
+==================
+
+The most flexible way to include Longbow into other software, is to integrate at an API level, this means that developers of other software can use Longbow in a seemless way without having to make external calls to the executable. There are many benefits to doing this, such as being able to create internal data structures directly, without having to firstly create Longbow configuration files, you can get access to the logging information and show this to users in a way you define and can interact with the Longbow exceptions.
+
+Over the next few months, this part of the documentation will be developed further. To get you started though, the easiest way to get going with integrating Longbow into your software, is to copy what the longbow() method is doing, for some developers simply calling this method using the "parameters" dictionary to override internal configuration will be all that is needed. But for others, a more fine grain approach will be neccessary. We will be adding examples of this to this section over the coming months.
+