Merge 4e5cd26 into a1e2da6

docs/Makefile

@@ -20,3 +20,4 @@ help:
 %: Makefile
 	@$(SPHINXAPIDOC) $(MISCDOCFLAGS) -s $(DOCOUTPUT) -o $(OUTPUTDIR) $(SRCPROJECT) $(IGNORE)
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	git checkout master -- _rtd/landing.md

docs/_rtd/landing.md

@@ -1,3 +1,6 @@
 ## Welcome to ARK
 
-Add a nice welcome message, and possibly link the quickstart guide as well.
+Thanks for choosing `ark`! `ark` is one of several libraries developed by [Angelo Lab](https://www.angelolab.com) affiliated with the Department of Pathology at Stanford University which uses Multiplexed Ion Beam Imaging (MIBI) for medical imaging analysis. Specifically, `ark` is a toolkit that assists with pre-processing tasks and post-processing analyis of image data generated from MIBI. 
+
+Want to get started? Please follow our quickstart guide as follows:
+

docs/_rtd/virtualenv.md

@@ -26,9 +26,9 @@ To verify installation, activate your `conda` environment with `conda activate <
 
 Note that you will not have access to `ark` or the other libraries inside `requirements.txt` outside of this virtual environment. 
 
-You're now set to start working with `ark-analysis`! Please look at [our contributing guidelines](contributing.md) for more information about development. For detailed explanations of the functions available to you in `ark`, please consult the Libraries section of this documentation. 
+You're now set to start working with `ark-analysis`! Please look at [our contributing guidelines](contributing.html) for more information about development. For detailed explanations of the functions available to you in `ark`, please consult the Libraries section of this documentation. 
 
 ### Using ark functions directly
 
-If you will only be using functions in `ark` without developing on top of it, do not clone the repo. Simply run `pip install ark-analysis` to gain access to our functions. To verify installation, type `conda list ark-analysis` after completion. If `ark-analysis` is listed, the installation was successful. You can now access the `ark` library by running `import ark`.
+If you will only be using functions in `ark` without developing on top of it, do not clone the repo. Simply run `pip install ark-analysis` inside the virtual environment to gain access to our functions. To verify installation, type `conda list ark-analysis` after completion. If `ark-analysis` is listed, the installation was successful. You can now access the `ark` library with `import ark`.
 

docs/conf.py

@@ -147,17 +147,52 @@
 intersphinx_cache_limit = 0
 
 
+# this function appends the proper lines and formatting to landing.md
+# so it can get displayed properly
+def append_readme():
+    with open(os.path.join('..', 'README.md')) as fin, open(os.path.join('_rtd', 'landing.md'), 'a') as fout:
+        # flag to identify when to start writing to file, doing this because we don't want to
+        # include build or covarage status nor the ark-analysis heading
+        seen_heading = False
+
+        for line in fin:
+            # once we've seen an h2 heading, we can start writing to file
+            # we also append an extra '#' to the line to downgrade to an h3 heading
+            # so that it can display comfortably on ReadTheDocs
+            if line.startswith('##'):
+                seen_heading = True
+                line = '#' + line
+
+            # append line to landing.md
+            if seen_heading:
+                fout.write(line)
+
+
 # this we'll need to build the documentation from sphinx-apidoc ourselves
 def run_apidoc(_):
+    # the parent directory we will begin snaking through to find documentation
     module = '../ark'
+
+    # we want the documents to be markdown files
     output_ext = 'md'
+
+    # we want to store the documentation in the _markdown folder on the ReadTheDocs server
     output_path = '_markdown'
+
+    # the sphinx-apidoc command to run
     cmd_path = 'sphinx-apidoc'
+
+    # do not generate any documentation for test files
     ignore = '../ark/*/*_test.py'
 
+    # should probably remove this
     if hasattr(sys, 'real_prefix'):
         cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
 
+    # append the readme to landing.md before running sphinx apidoc build
+    append_readme()
+
+    # run sphinx-apidoc to build documentation from Google docstrings
     subprocess.check_call([cmd_path, '-f', '-T', '-s', output_ext, '-o', output_path, module, ignore])