Move documentation to Documenter

.travis.yml

@@ -10,8 +10,22 @@ branches:
     - master
 notifications:
   email: false
-after_success:
-  - julia -e 'using Pkg;
-              Pkg.add("Coverage");
-              using Coverage;
-              Coveralls.submit(Coveralls.process_folder())'
+jobs:
+  include:
+    - stage: "Documentation"
+      os: linux
+      julia: 1.5
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));
+                                               Pkg.instantiate()'
+        - julia --project=docs/ docs/make.jl
+    - stage: "Code coverage"
+      julia: 1.5
+      os: linux
+      script:
+        - julia -e 'using Pkg;
+          Pkg.build(); Pkg.test(coverage=true);
+          import Circuitscape; cd(joinpath(dirname(pathof(Circuitscape)),".."));
+          Pkg.add("Coverage");
+          using Coverage;
+          Codecov.submit(Codecov.process_folder())'

README.md

@@ -3,6 +3,8 @@
 Linux and OSX: [![Build Status](https://travis-ci.com/Circuitscape/Circuitscape.jl.svg?branch=master)](https://travis-ci.com/Circuitscape/Circuitscape.jl)
 [![Coverage Status](https://coveralls.io/repos/github/Circuitscape/Circuitscape.jl/badge.svg?branch=master)](https://coveralls.io/github/Circuitscape/Circuitscape.jl?branch=master)
 [![codecov.io](http://codecov.io/github/Circuitscape/Circuitscape.jl/coverage.svg?branch=master)](http://codecov.io/github/Circuitscape/Circuitscape.jl?branch=master)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.circuitscape.org/Circuitscape.jl/stable)
+[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.circuitscape.org/Circuitscape.jl/dev)
 
 Windows: [![Build status](https://ci.appveyor.com/api/projects/status/4a8u8985hq2mt569?svg=true)](https://ci.appveyor.com/project/ranjanan/circuitscape-jl)
 

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,18 @@
+using Circuitscape, Documenter
+
+makedocs(
+    sitename = "Circuitscape.jl Documentation",
+    pages = ["Home" => "index.md",
+             "User Guide" => "usage.md",
+             "Inputs, Outputs and Options" => "options.md", 
+             "On Solvers and Computation Time" => "compute.md", 
+             "Calling Circuitscape from other Programs" => "otherprog.md", 
+             "Logging Options" => "logging.md"
+    ]
+)
+
+deploydocs(
+    repo = "github.com/Circuitscape/Circuitscape.jl.git",
+    devbranch = "master",
+    devurl = "latest"
+)

docs/src/compute.md

@@ -0,0 +1,9 @@
+# 10\. Computational limitations, speed, and landscape size
+
+We have tested this code on landscapes with up to 100 million cells. Increasing numbers of connections using diagonal (eight neighbor) connections will decrease the size of landscapes that can be analyzed. Also, increasing landscape size or numbers of focal nodes will increase computation time. We anticipate future improvements will increase the program's speed. Note that due to the matrix algebra involved with solving many pairs of focal nodes, Circuitscape will run much faster when focal points (each focal node falls within only one grid cell), rather than focal regions (at least one focal node occupies multiple grid cells), are used.
+
+## Important note: memory limitations
+
+Insufficient RAM is the most common cause of program errors. 32-bit systems will be particularly limited because no more than 2GB of memory can be addressed by any one process, limiting solvable landscapes to approximately 2-6 million cells, depending on the properties of the grid. Larger grids can be solved on 64-bit systems with large amounts of RAM.
+
+There are several ways to increase the solvable grid size. These include closing all other programs (especially those that require lots of RAM such as ArcGIS), setting impermeable areas of your resistance map to NODATA, using focal points instead of regions in pairwise mode, connecting cells to their four neighbors only, and not creating current maps. Also, the one-to-all and all- to-one modes typically use less memory (and run more quickly) than the pairwise mode. In particular, the all-to-one mode can be an alternative to the pairwise mode when the goal is to produce a cumulative map of important connectivity areas among multiple source/target patches. Still, coarsening your grids (using larger cell sizes) may be necessary; doing so often produces results that are qualitatively similar to those obtained with smaller cell sizes. See McRae et al. 2008 for details of effects of using coarser grids.

docs/src/index.md

@@ -0,0 +1,103 @@
+# Circuitscape Documentation
+
+Circuitscape is an open-source Julia program that uses circuit theory to model connectivity 
+in heterogeneous landscapes. Its most common applications include modeling movement and gene
+flow of plants and animals, as well as identifying areas important for connectivity 
+conservation. Circuit theory complements commonly-used connectivity models because of its 
+connections to random walk theory and its ability to simultaneously evaluate contributions 
+of multiple dispersal pathways. Landscapes are represented as conductive surfaces, with 
+low resistances assigned to landscape features types that are most permeable to movement 
+or best promote gene flow, and high resistances assigned to movement barriers. Effective 
+resistances, current flow, and voltages calculated across the landscapes can then be 
+related to ecological processes, such as individual movement and gene flow.
+
+More detail about the underlying model, its parameterization, and potential applications 
+in ecology, evolution, and conservation planning can be found in McRae (2006) and 
+McRae et al. (2008).
+
+More detail about implementation can be found in the 
+[Circuitscape In Julia paper](https://proceedings.juliacon.org/papers/10.21105/jcon.00058). 
+
+
+# Quick Start Guide
+
+This is a quick start guide. If you're looking for basics on how to use Circuitscape, 
+refer to the usage guide. 
+
+To run Circuitscape, you need to install the [latest version]() of Julia. 
+At the Julia prompt, install the Circuitscape package by running the following code
+
+```julia
+using Pkg
+Pkg.add("Circuitscape")
+```
+
+You can also install Circuitscape in a 
+[local project](https://julialang.github.io/Pkg.jl/v1/environments/) as well. 
+
+## Running a job
+
+A Circuitscape job is fully described by an INI file. This configuration file consists of
+file paths to data as well as flag values. A detailed list of fields found an in an
+INI File can be found in the Files and Flags section. Examples can be found in the 
+[test folder](https://github.com/Circuitscape/Circuitscape.jl/tree/master/test/input). You
+can also use a builtin UI to build Circuitscape jobs. For more on that, skip ahead to 
+Building a Circuitscape Job. 
+
+If you do have your INI file handy, you can run the job by: 
+```julia
+compute("myjob.ini")
+```
+## Building a Circuitscape Job
+
+![](https://raw.githubusercontent.com/Circuitscape/www.circuitscape.org/RA/inibuilder/assets/inibuilder.gif)
+
+The builder is kicked off by calling the `start()` function from the Julia prompt. It will
+build an INI file for you step by step, and either run the job directly or write the
+final INI file to a specified location. You can exit the builder at any time by hitting 
+Cntrl+C. 
+
+Please note that this version of Circuitscape **does not** come with a GUI. 
+
+You can, as a fallback, manually write your own INI file by copying and pasting an example 
+from the [test folder]() and change values as needed.    
+
+## Citing Circuitscape
+
+Please use the following to cite Circuitscape: 
+
+```bibtex
+@article{Anantharaman2020,
+  doi = {10.21105/jcon.00058},
+  url = {https://doi.org/10.21105/jcon.00058},
+  year = {2020},
+  publisher = {The Open Journal},
+  volume = {1},
+  number = {1},
+  pages = {58},
+  author = {Ranjan Anantharaman and Kimberly Hall and Viral B. Shah and Alan Edelman},
+  title = {Circuitscape in Julia: High Performance Connectivity Modelling to Support Conservation Decisions},
+  journal = {Proceedings of the JuliaCon Conferences}
+}
+```
+
+# Further Reading
+
+Beier, P., W. Spencer, R. Baldwin, and B.H. McRae. 2011\. Best science practices for developing regional connectivity maps. Conservation Biology 25(5): 879-892
+
+Dickson B.G., G.W. Roemer, B.H. McRae, and J.M. Rundall. 2013\. Models of regional habitat quality and connectivity for pumas (_Puma concolor_) in the southwestern United States. PLoS ONE 8(12): e81898\. doi:10.1371/journal.pone.0081898
+
+McRae, B.H. 2006\. Isolation by resistance. Evolution 60:1551-1561.
+
+McRae, B.H. and P. Beier. 2007\. Circuit theory predicts Gene flow in plant and animal populations. Proceedings of the National Academy of Sciences of the USA 104:19885-19890.
+
+McRae, B.H., B.G. Dickson, T.H. Keitt, and V.B. Shah. 2008\. Using circuit theory to model connectivity in ecology and conservation. Ecology 10: 2712-2724.
+
+Shah, V.B. 2007\. An Interactive System for Combinatorial Scientific Computing with an Emphasis on Programmer Productivity. PhD thesis, University of California, Santa Barbara.
+
+Shah,V.B. and B.H. McRae. 2008\. Circuitscape: a tool for landscape ecology. In: G. Varoquaux, T. Vaught, J. Millman (Eds.). Proceedings of the 7th Python in Science Conference (SciPy 2008), pp. 62-66.
+
+Spear, S.F., N. Balkenhol, M.-J. Fortin, B.H. McRae and K. Scribner. 2010\. Use of resistance surfaces for landscape genetic studies: Considerations of parameterization and analysis. Molecular Ecology 19(17): 3576-3591.
+
+Zeller K.A., McGarigal K., and Whiteley A.R. 2012\. Estimating landscape resistance to movement: a review. Landscape Ecology 27: 777-797.
+

docs/src/logging.md

@@ -0,0 +1,13 @@
+### The Log Window
+
+#### Level
+
+The default level (INFO) sends a moderate amount of information on the program's progress to the terminal window. DEBUG gives more, and the other options give less.
+
+#### Log completion times
+
+Writes names of operations and completion times for each to the terminal window.
+
+#### Send to log file
+
+Information printed to the screen will also be saved in a log file in the output directory.