Merge pull request #38 from EOSC-synergy/dev

Dev

.appveyor.yml

@@ -0,0 +1,84 @@
+# See https://www.appveyor.com/docs/getting-started-with-appveyor-for-linux/
+# Don't build branches with a PR, since their build will be created with the PR itself. 
+# Otherwise there would be two builds -- one for the PR and one for the branch.
+# If you're having issues with getting your PR to build, make sure there are no merge conflicts.
+skip_branch_with_pr: true
+
+# Enable 'Do not build on "Push" events' in the AppVeyor project settings
+# to only build commits from pull requests
+branches:
+  only:
+    - main
+    - master
+
+# Only run AppVeyor on commits that modify at least one of the following files
+# Delete these lines to run AppVeyor on all main/master branch commits
+only_commits:
+  files:
+    - .appveyor.yml
+    - build/
+    - ci/install.sh
+    - content/
+
+image: ubuntu
+services:
+  - docker
+
+# Set SPELLCHECK to true to enable Pandoc spellchecking
+environment:
+  SPELLCHECK: true
+
+install:
+  # Create the message with the triggering commit before install so it is
+  # available if the build fails
+  - TRIGGERING_COMMIT=${APPVEYOR_PULL_REQUEST_HEAD_COMMIT:-APPVEYOR_REPO_COMMIT}
+  - JOB_MESSAGE=" for commit $TRIGGERING_COMMIT "
+  - source ci/install.sh
+
+test_script:
+  - bash build/build.sh
+  - MANUSCRIPT_FILENAME=manuscript-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}
+  - cp output/manuscript.html $MANUSCRIPT_FILENAME.html
+  - cp output/manuscript.pdf $MANUSCRIPT_FILENAME.pdf
+  - appveyor PushArtifact $MANUSCRIPT_FILENAME.html
+  - appveyor PushArtifact $MANUSCRIPT_FILENAME.pdf
+  - |
+      if [ "${SPELLCHECK:-}" = "true" ]; then
+        SPELLING_ERRORS_FILENAME=spelling-errors-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}.txt
+        cp output/spelling-errors.txt $SPELLING_ERRORS_FILENAME
+        appveyor PushArtifact $SPELLING_ERRORS_FILENAME
+        SPELLING_ERROR_LOCATIONS_FILENAME=spelling-error-locations-$APPVEYOR_BUILD_VERSION-${TRIGGERING_COMMIT:0:7}.txt
+        cp output/spelling-error-locations.txt $SPELLING_ERROR_LOCATIONS_FILENAME
+        appveyor PushArtifact $SPELLING_ERROR_LOCATIONS_FILENAME
+      fi
+
+build: off
+
+cache:
+  - ci/cache
+
+on_success:
+  - echo "Artifacts available from $APPVEYOR_URL/project/$APPVEYOR_ACCOUNT_NAME/$APPVEYOR_PROJECT_SLUG/builds/$APPVEYOR_BUILD_ID/artifacts"
+  - echo "Updated PDF available from $APPVEYOR_URL/api/buildjobs/$APPVEYOR_JOB_ID/artifacts/$MANUSCRIPT_FILENAME.pdf"
+  - appveyor AddMessage "$JOB_MESSAGE is now complete."
+  - |
+      if [ "${SPELLCHECK:-}" = "true" ]; then
+        SPELLING_ERROR_COUNT=($(wc -l $SPELLING_ERROR_LOCATIONS_FILENAME))
+        appveyor AddMessage " <details><summary>Found $SPELLING_ERROR_COUNT potential spelling error(s). Preview:</summary>$(head -n 100 $SPELLING_ERROR_LOCATIONS_FILENAME)"
+        appveyor AddMessage "... </details>"
+      fi
+
+on_failure:
+  - appveyor AddMessage "$JOB_MESSAGE failed."
+
+# The following lines can be safely deleted, which will disable AppVeyorBot
+# notifications in GitHub pull requests
+# Notifications use Mustache templates http://mustache.github.io/mustache.5.html
+# See https://www.appveyor.com/docs/notifications/#customizing-message-template
+# for available variables
+notifications:
+  - provider: GitHubPullRequest
+    template: "AppVeyor [build {{buildVersion}}]({{buildUrl}})
+      {{#jobs}}{{#messages}}{{{message}}}{{/messages}}{{/jobs}}
+      {{#passed}}The rendered manuscript from this build is temporarily available for download at:\n\n
+      {{#jobs}}{{#artifacts}}- [`{{fileName}}`]({{permalink}})\n{{/artifacts}}{{/jobs}}{{/passed}}"

.github/workflows/manubot.yaml

@@ -2,42 +2,71 @@ name: Manubot
 on:
   push:
     branches:
+      - main
       - master
   pull_request:
     branches:
+      - main
       - master
+  workflow_dispatch:
+    inputs:
+      BUILD_PDF:
+        description: generate PDF output (true or false)
+        default: "true"
+      BUILD_DOCX:
+        description: generate DOCX output (true or false)
+        default: "false"
+      BUILD_LATEX:
+        description: generate LaTeX output (true or false)
+        default: "false"
 jobs:
   manubot:
     name: Manubot
     runs-on: ubuntu-latest
     env:
       GITHUB_PULL_REQUEST_SHA: ${{ github.event.pull_request.head.sha }}
+      SPELLCHECK: true
     steps:
-      - name: Set Environment Variables
-        run: |
-          TRIGGERING_SHA=${GITHUB_PULL_REQUEST_SHA:-$GITHUB_SHA}
-          TRIGGERING_SHA_7=${TRIGGERING_SHA::7}
-          echo "::set-env name=TRIGGERING_SHA_7::$TRIGGERING_SHA_7"
-          echo "TRIGGERING_SHA: $TRIGGERING_SHA"
       - name: Checkout Repository
         uses: actions/checkout@v2
         with:
           # fetch entire commit history to support get_rootstock_commit
           fetch-depth: 0
+      - name: Set Environment Variables (Workflow Dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          echo "BUILD_PDF=${{ github.event.inputs.BUILD_PDF }}" >> $GITHUB_ENV
+          echo "BUILD_DOCX=${{ github.event.inputs.BUILD_DOCX }}" >> $GITHUB_ENV
+          echo "BUILD_LATEX=${{ github.event.inputs.BUILD_LATEX }}" >> $GITHUB_ENV
+      - name: Set Environment Variables
+        run: |
+          TRIGGERING_SHA=${GITHUB_PULL_REQUEST_SHA:-$GITHUB_SHA}
+          echo "TRIGGERING_SHA_7=${TRIGGERING_SHA::7}" >> $GITHUB_ENV
+          echo "TRIGGERING_SHA: $TRIGGERING_SHA"
+          DEFAULT_BRANCH=$(git remote show origin | grep --perl-regexp --only-matching "(?<=HEAD branch: ).+")
+          echo "DEFAULT_BRANCH=${DEFAULT_BRANCH}" >> $GITHUB_ENV
+          echo "DEFAULT_BRANCH_REF=refs/heads/$DEFAULT_BRANCH" >> $GITHUB_ENV
+          echo "DEFAULT_BRANCH=$DEFAULT_BRANCH"
       - name: Cache
         uses: actions/cache@v1
         with:
           path: ci/cache
           key: ci-cache-${{ github.ref }}
           restore-keys: |
-            ci-cache-refs/heads/master
+            ci-cache-${{ env.DEFAULT_BRANCH_REF }}
       - name: Install Environment
-        uses: goanpeca/setup-miniconda@v1
+        uses: conda-incubator/setup-miniconda@v2
         with:
           activate-environment: manubot
           environment-file: build/environment.yml
           auto-activate-base: false
           miniconda-version: 'latest'
+      - name: Install Spellcheck
+        shell: bash --login {0}
+        run: |
+          if [ "${SPELLCHECK:-}" = "true" ]; then
+            bash ci/install-spellcheck.sh
+          fi
       - name: Build Manuscript
         shell: bash --login {0}
         run: bash build/build.sh
@@ -47,11 +76,11 @@ jobs:
           name: manuscript-${{ github.run_id }}-${{ env.TRIGGERING_SHA_7 }}
           path: output
       - name: Deploy Manuscript
-        if: github.ref == 'refs/heads/master' && github.event_name == 'push' && !github.event.repository.fork
+        if: github.ref == env.DEFAULT_BRANCH_REF && github.event_name != 'pull_request' && !github.event.repository.fork
         env:
           MANUBOT_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           MANUBOT_SSH_PRIVATE_KEY: ${{ secrets.MANUBOT_SSH_PRIVATE_KEY }}
           CI_BUILD_WEB_URL: https://github.com/${{ github.repository }}/commit/${{ github.sha }}/checks
-          CI_JOB_WEB_URL: https://github.com/${{ github.repository }}/runs/${{ github.run_id }}
+          CI_JOB_WEB_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
         shell: bash --login {0}
         run: bash ci/deploy.sh

.gitignore

@@ -11,6 +11,9 @@ webpage/v
 # Manubot cache directory
 ci/cache
 
+# Pandoc filters downloaded during continuous integration setup
+build/pandoc/filters/spellcheck.lua
+
 # Python
 __pycache__/
 *.pyc

.travis.yml

@@ -0,0 +1,26 @@
+dist: trusty
+sudo: false
+language: generic
+services:
+  - docker
+branches:
+  only:
+    - main
+    - master
+env:
+  - SPELLCHECK=true
+install:
+  - source ci/install.sh
+script:
+  - bash build/build.sh
+cache:
+  directories:
+    - ci/cache
+deploy:
+  provider: script
+  script: bash ci/deploy.sh
+  skip_cleanup: true
+  on:
+    # branch kept as master since travis deployment is legacy.
+    branch: master
+    condition: $TRAVIS_EVENT_TYPE = "push" && (-v MANUBOT_SSH_PRIVATE_KEY || "${!encrypted_*}" != "")

README.md

@@ -43,7 +43,69 @@ Please check our [contribution](CONTRIBUTING.md) guide.
 
 ## Copyright Notice
 
+<<<<<<< HEAD
 Copyright © Members of the EOSC-Synergy collaborations, 2019-2020.
+=======
+### 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 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.
+
+### Local execution
+
+The easiest way to run Manubot is to use [continuous integration](#continuous-integration) to rebuild the manuscript when the content changes.
+If you want to build a Manubot manuscript 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 from this root directory.
+
+```sh
+# Activate the manubot conda environment (assumes conda version >= 4.4)
+conda activate manubot
+
+# Build the manuscript, saving outputs to the output directory
+bash build/build.sh
+
+# At this point, the HTML & PDF outputs will have been created. The remaining
+# commands are for serving the webpage to view the HTML manuscript locally.
+# This is required to view local images in the HTML output.
+
+# Configure the webpage directory
+manubot webpage
+
+# You can now open the manuscript webpage/index.html in a web browser.
+# Alternatively, open a local webserver at http://localhost:8000/ with the
+# following commands.
+cd webpage
+python -m http.server
+```
+
+Sometimes it's helpful to monitor the content directory and automatically rebuild the manuscript when a change is detected.
+The following command, while running, will trigger both the `build.sh` script and `manubot webpage` command upon content changes:
+
+```sh
+bash build/autobuild.sh
+```
+
+### Continuous Integration
+
+Whenever a pull request is opened, CI (continuous integration) 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 CI logs for the cause of failure and revise your pull request accordingly.
+
+When a commit to the `main` branch occurs (for example, when a pull request is merged), CI builds the manuscript and writes the results to the [`gh-pages`](https://github.com/manubot/rootstock/tree/gh-pages) and [`output`](https://github.com/manubot/rootstock/tree/output) branches.
+The `gh-pages` branch uses [GitHub Pages](https://pages.github.com/) to host the following URLs:
+
++ **HTML manuscript** at https://manubot.github.io/rootstock/
++ **PDF manuscript** at https://manubot.github.io/rootstock/manuscript.pdf
+
+For continuous integration configuration details, see [`.github/workflows/manubot.yaml`](.github/workflows/manubot.yaml) if using GitHub Actions or [`.travis.yml`](.travis.yml) if using Travis CI.
+>>>>>>> 9a448fe6edb477fb98065d5b83d206b1ca489cee
 
 ## License