Merge PR #681 to update Manubot

Update the Deep Review with latest Manubot

.gitignore

@@ -1,11 +1,11 @@
 # Generated manuscript output files
-output/index.html
-output/deep-review.pdf
-output/*.ots
+output/*
+!output/README.md
 
-# Generated reference files
-references/generated/*
-!references/generated/README.md
+webpage/*.ots
+
+# Manubot cache directory
+ci/cache
 
 # Python
 __pycache__/

.travis.yml

@@ -5,22 +5,21 @@ branches:
   only:
     - master
 before_install:
-  - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
+  - wget https://repo.continuum.io/miniconda/Miniconda3-4.3.21-Linux-x86_64.sh
     --output-document miniconda.sh
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH="$HOME/miniconda/bin:$PATH"
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
-  - conda update --quiet conda
   - conda info --all
 install:
   - conda env create --quiet --file build/environment.yml
-  - source activate deepreview
+  - source activate manubot
 script:
   - sh build/build.sh
 cache:
   directories:
-    - references/generated
+    - ci/cache
 after_success:
   - test $TRAVIS_BRANCH = "master" &&
     test $TRAVIS_PULL_REQUEST = "false" &&

CONTRIBUTING.md

@@ -1,5 +1,8 @@
 # Contribution guidelines for the deep-review repository
 
+Please see [`USAGE.md`](USAGE.md) for information on how to use the Manubot for writing the manuscript.
+Below you'll find information on the contribution workflow for the Deep Review.
+
 ## Issues
 
 We'll use issues for discussion of papers, section outlines, and other
@@ -32,33 +35,3 @@ Before a repository maintainer merges a pull request, there must be at least
 one affirmative review. If there is any unaddressed criticism or disapproval,
 a repository maintainer will determine how to proceed and may wait for
 additional feedback.
-
-## Markdown
-
-The paper will be written using markdown. Markdown files use the `.md`
-extension. Check out the [CommonMark Help](http://commonmark.org/help/) page
-for an introduction to formatting options provided by markdown. In addition, to
-standard markdown features, we support [markdown
-tables](https://help.github.com/articles/organizing-information-with-tables/
-"GitHub Help: Organizing information with tables") and a custom citation syntax.
-Check out [Tables Generator](http://www.tablesgenerator.com/markdown_tables) for
-creating markdown tables.
-
-The custom citation guidelines are as follows:
-
-1. Always use a DOI for the version of record if available. Cite DOIs like
-  `[@doi:10.15363/thinklab.4]`.
-2. If the version of record doesn't have a DOI but does have a PubMed ID, cite
-  like `[@pmid:26158728]`.
-3. If the article is an _arXiv_ preprint, cite like `[@arxiv:1508.06576]`.
-4. If and only if the article has none of the above, cite with the URL like
-  `[@url:http://openreview.net/pdf?id=Sk-oDY9ge]`.
-
-You cite multiple items at once like `[@doi:10.15363/thinklab.4 @pmid:26158728
-@arxiv:1508.06576]`.
-
-For improved readability, you can (but are not required to) use a tag. For
-example, you can add a reference to the tag `Zhou2015_deep_sea` using the
-following syntax: `[@tag:Zhou2015_deep_sea]`. If you add references that use
-tags, make sure to add those tags and their corresponding citations to
-[`references/tags.tsv`](references/tags.tsv).

README.md

@@ -1,21 +1,22 @@
 # Opportunities and obstacles for deep learning in biology and medicine
 
+[![HTML Manuscript](https://img.shields.io/badge/manuscript-HTML-blue.svg)](https://greenelab.github.io/deep-review/)
+[![PDF Manuscript](https://img.shields.io/badge/manuscript-PDF-blue.svg)](https://greenelab.github.io/deep-review/manuscript.pdf)
+[![Build Status](https://travis-ci.org/greenelab/deep-review.svg?branch=master)](https://travis-ci.org/greenelab/deep-review)
 [![Code Climate](https://codeclimate.com/github/greenelab/deep-review/badges/gpa.svg)](https://codeclimate.com/github/greenelab/deep-review)
 
+## Manuscript description
 
-The most current version of the `master` branch is built by continuous integration
-and [available via gh-pages](https://greenelab.github.io/deep-review/). To see
-what's incoming, check the
-[open pull requests](https://github.com/greenelab/deep-review/pulls).
+To see what's incoming, check the [open pull requests](https://github.com/greenelab/deep-review/pulls).
 
-## Current Status - Submitted
+#### Current Status - Submitted
 
 We have submitted the manuscript to the journal. A preprint is available at
 [bioRxiv](https://doi.org/10.1101/142760). We are still accepting contributions
 to improve this work. Feel free to create an issue, contribute some text via a
 pull request, and pitch in. Authorship criteria remain the same.
 
-## More about the manuscript.
+#### More about the manuscript.
 
 We have the opportunity to write a headline review for *Journal of the Royal
 Society Interface* on a topic overlapping the computer and life sciences in the
@@ -47,15 +48,15 @@ model. Anyone whose contributions meet the ICJME standards of authorship will be
 included as an author on the manuscript. I can't guarantee that it will be
 accepted, but I look forward to trying this approach out.
 
-## Status Report on 12/21
+#### Status Report on 12/21
 
 We are now actively writing the review. Markdown files can be found in the
 `sections/` folder. Please claim a section, create a fork, and contribute that
 section back via a pull request. To see what a pull request into the paper
 entails, check out [PR #147](https://github.com/greenelab/deep-review/pull/147)
 from [@evancofer](https://github.com/evancofer).
 
-## Status Report on 10/26
+#### Status Report on 10/26
 
 We are now actively outlining the review sections and will begin writing
 soon.  The goal is to have a complete draft in about a month.  The action items
@@ -69,7 +70,7 @@ from the 8/25 status report below are still applicable.  In addition, you can:
 3. Outline sections that do not have stubs with a pull request and discuss
    them with other co-authors in the pull request comments.
 
-## Status Report on 8/25
+#### Status Report on 8/25
 
 Over the first three weeks of this project, we've developed an initial guiding
 question; collaboratively read, summarized, and discussed existing literature
@@ -94,21 +95,62 @@ argue about the answer to the question that we coalesce on with
 [#88](https://github.com/greenelab/deep-review/issues/88) for each area that the
 review will cover.
 
-## Continuous Integration
+## Manubot
+
+<!-- usage note: do not edit this section -->
+
+Manubot is a system for writing scholarly manuscripts via GitHub.
+Manubot automates citations and references, versions manuscripts using git, and enables collaborative writing via GitHub.
+The [Manubot Rootstock repository](https://git.io/vQSvo) is a general purpose template for creating new Manubot instances, as detailed in [`SETUP.md`](SETUP.md).
+See [`USAGE.md`](USAGE.md) for documentation how to write a manuscript.
+
+### Repository directories & files
+
+The directories are as follows:
+
++ [`content`](content) contains the manuscript source, which includes markdown files as well as inputs for citations and references.
+  See [`USAGE.md`](USAGE.md) for more information.
++ [`output`](output) contains the outputs (generated files) from the manubot including the resulting manuscripts.
+  You should not edit these files manually, because they will get overwritten.
++ [`webpage`](webpage) is a directory meant to be rendered as a static webpage for viewing the HTML manuscript.
++ [`build`](build) contains commands and tools for building the manuscript.
++ [`ci`](ci) contains files necessary for deployment via continuous integration.
+  For the CI configuration, see [`.travis.yml`](.travis.yml).
+
+### Local execution
+
+To run the Manubot locally, install the [conda](https://conda.io) environment as described in [`build`](build).
+Then, you can build the manuscript on POSIX systems by running the following commands.
+
+```sh
+# Activate the manubot conda environment
+source activate manubot
+
+# Build the manuscript
+sh build/build.sh
+
+# Or monitor the content directory, and automatically rebuild the manuscript
+# when a change is detected.
+sh build/autobuild.sh
+
+# View the manuscript locally at http://localhost:8000/
+cd webpage
+python -m http.server
+```
+
+### Continuous Integration
 
 [![Build Status](https://travis-ci.org/greenelab/deep-review.svg?branch=master)](https://travis-ci.org/greenelab/deep-review)
 
-When you make a pull request, Travis CI will test whether your changes break the build process to generate the formatted manuscript.
-The build process aims to detect common errors, such as invalid references.
-If your build fails, see the Travis CI logs for the cause of failure and revise your pull request accordingly.
+Whenever a pull request is opened, Travis CI will test whether the changes break the build process to generate a formatted manuscript.
+The build process aims to detect common errors, such as invalid citations.
+If your pull request build fails, see the Travis CI logs for the cause of failure and revise your pull request accordingly.
 
-When a pull request is merged, Travis CI performs the build and writes the results to the [`gh-pages`](https://github.com/greenelab/deep-review/tree/gh-pages) and [`references`](https://github.com/greenelab/deep-review/tree/references) branches.
-The `gh-pages` branch hosts the following URLs:
+When a commit to the `master` branch occurs (for example, when a pull request is merged), Travis CI builds the manuscript and writes the results to the [`gh-pages`](https://github.com/greenelab/deep-review/tree/gh-pages) and [`output`](https://github.com/greenelab/deep-review/tree/output) branches.
+The `gh-pages` branch uses [GitHub Pages](https://pages.github.com/) to host the following URLs:
 
-+ **HTML manuscript** at https://greenelab.github.io/deep-review/<br>
-  short URL: https://git.io/vytJN
-+ **PDF manuscript** at https://greenelab.github.io/deep-review/deep-review.pdf<br>
-  short URL: https://git.io/vytJ5
++ **HTML manuscript** at https://greenelab.github.io/deep-review/
++ **PDF manuscript** at https://greenelab.github.io/deep-review/manuscript.pdf
 
 For continuous integration configuration details, see [`.travis.yml`](.travis.yml).
 
@@ -121,11 +163,11 @@ Except when noted otherwise, the entirety of this repository is licensed under a
 Please attribute by linking to https://github.com/greenelab/deep-review.
 
 Since CC BY is not ideal for code and data, certain repository components are also released under the CC0 1.0 public domain dedication ([`LICENSE-CC0.md`](LICENSE-CC0.md)).
-All files matched by the following blog patterns are dual licensed under CC BY 4.0 and CC0 1.0:
+All files matched by the following glob patterns are dual licensed under CC BY 4.0 and CC0 1.0:
 
 + `*.sh`
 + `*.py`
-+ `*.yml`
++ `*.yml` / `*.yaml`
 + `*.json`
 + `*.bib`
 + `*.tsv`
@@ -136,10 +178,10 @@ All other files are only available under CC BY 4.0, including:
 + `*.md`
 + `*.html`
 + `*.pdf`
++ `*.docx`
 
 Except for the following files with different licenses:
 
-+ `build/assets/anchors.js` which is [released](https://www.bryanbraun.com/anchorjs/)
-  under an [MIT License](https://opensource.org/licenses/MIT)
++ `build/assets/anchors.js` which is [released](https://www.bryanbraun.com/anchorjs/) under an [MIT License](https://opensource.org/licenses/MIT)
 
 Please open [an issue](https://github.com/greenelab/deep-review/issues) for any question related to licensing.