Merge pull request #174 from cmu-delphi/release

12/14 Release

Author: tildechris

.gitattributes

@@ -0,0 +1,131 @@
+# These settings are for any web project
+
+# Handle line endings automatically for files detected as text
+# and leave all files detected as binary untouched.
+* text=auto eol=lf
+
+#
+# The above will handle all files NOT found below
+#
+
+#
+## These files are text and should be normalized (Convert crlf => lf)
+#
+
+# source code
+*.php text
+*.css text
+*.sass text
+*.scss text
+*.less text
+*.styl text
+*.js text
+*.ts text
+*.coffee text
+*.json text
+*.htm text
+*.html text
+*.xml text
+*.txt text
+*.ini text
+*.inc text
+*.pl text
+*.rb text
+*.py text
+*.scm text
+*.sql text
+*.sh text eof=LF
+*.bat text
+*.R text
+
+# templates
+*.hbt text
+*.jade text
+*.haml text
+*.hbs text
+*.dot text
+*.tmpl text
+*.phtml text
+
+# server config
+.htaccess text
+
+# git config
+.gitattributes text
+.gitignore text
+
+# code analysis config
+.jshintrc text
+.jscsrc text
+.jshintignore text
+.csslintrc text
+
+# misc config
+*.yaml text
+*.yml text
+*.editorconfig text
+*.toml text
+
+# build config
+*.npmignore text
+*.bowerrc text
+*.prettierignore text
+Dockerfile text eof=LF
+
+# Heroku
+Procfile text
+.slugignore text
+
+# Documentation
+*.md text
+LICENSE text
+AUTHORS text
+
+
+#
+## These files are binary and should be left untouched
+#
+
+# (binary is a macro for -text -diff)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.mov binary
+*.mp4 binary
+*.mp3 binary
+*.flv binary
+*.fla binary
+*.swf binary
+*.gz binary
+*.zip binary
+*.7z binary
+*.ttf binary
+*.pyc binary
+*.pdf binary
+
+# Source files
+# ============
+*.pxd		text
+*.py 		text
+*.py3 		text
+*.pyw 		text
+*.pyx  		text
+*.sh        text eol=lf
+*.json      text
+
+# Binary files
+# ============
+*.db		binary
+*.p 		binary
+*.pkl 		binary
+*.pyc 		binary
+*.pyd		binary
+*.pyo 		binary
+
+# Note: .db, .p, and .pkl files are associated
+# with the python modules ``pickle``, ``dbm.*``,
+# ``shelve``, ``marshal``, ``anydbm``, & ``bsddb``
+# (among others).
+*.rda       binary

.github/workflows/ci.yaml

@@ -1,9 +1,9 @@
 on:
   push:
     paths: # run only when an Rmd file changes
-     - '**.Rmd'
-     - 'environment.yml'
-     - '.github/workflows/ci.yaml'
+      - "**.Rmd"
+      - "environment.yml"
+      - ".github/workflows/ci.yaml"
 
 name: ci
 
@@ -17,7 +17,7 @@ jobs:
           fetch-depth: 3
       - name: Cache Conda
         uses: actions/cache@v1
-        with:          
+        with:
           path: ~/conda_pkgs_dir
           key: ${{ runner.os }}-conda6-${{ hashFiles('environment.yml') }}
           restore-keys: |
@@ -50,20 +50,22 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-blogdown2-
       - name: Build site
-        shell: bash -l {0}        
+        shell: bash -l {0}
         run: |
           npm run build:blog
-      
+
       - uses: actions/setup-node@v1
         with:
-          node-version: '12'
+          node-version: "12"
       - uses: actions/cache@v2
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-node-
       - run: npm ci
+      - name: Lint
+        run: npm run lint
       - name: Build
         run: npm run build
 

.github/workflows/ci_fast.yaml

@@ -1,9 +1,9 @@
 on:
   push:
     paths-ignore: # don't run the fast version when an Rmd file changes
-     - '**.Rmd'
-     - 'environment.yml'
-     - '.github/workflows/ci.yaml'
+      - "**.Rmd"
+      - "environment.yml"
+      - ".github/workflows/ci.yaml"
 
 name: ci_fast
 
@@ -14,18 +14,20 @@ jobs:
       - uses: actions/checkout@v2
         with:
           # submodules: true  # Fetch Hugo themes (true OR recursive)
-          fetch-depth: 3    # Fetch all history for .GitInfo and .Lastmod   
-      
+          fetch-depth: 3 # Fetch all history for .GitInfo and .Lastmod
+
       - uses: actions/setup-node@v1
         with:
-          node-version: '12'
+          node-version: "12"
       - uses: actions/cache@v2
         with:
           path: ~/.npm
           key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
             ${{ runner.os }}-node-
       - run: npm ci
+      - name: Lint
+        run: npm run lint
       - name: Build
         run: npm run build
 

.gitignore

@@ -1,7 +1,6 @@
 /public
 /resources/_gen
 *.exe
-/.vscode
 /blogdown
 /.Rhistory
 *_cache

.prettierignore

@@ -0,0 +1,30 @@
+*.toml
+*.jpg
+*.png
+*.rda
+*.rdx
+*.RData
+*.svg
+/blogdown
+/.htaccess
+/.Rhistory
+.gitignore
+.prettierignore
+/.gitattributes
+/LICENSE
+/package-lock.json
+/content/blog/**/*.html
+/static
+/public
+/Dockerfile
+/resources
+/assets
+*.woff
+*.ttf
+*.woff2
+*.R
+*.xml
+*.Rmd
+*.md
+*.jpeg
+*.ico

.prettierrc.js

@@ -0,0 +1,14 @@
+module.exports = {
+  printWidth: 120,
+  semi: true,
+  trailingComma: "es5",
+
+  overrides: [
+    {
+      files: ["*.html"],
+      options: {
+        parser: "go-template",
+      },
+    },
+  ],
+};

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["esbenp.prettier-vscode"]
+}

.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": true,
+  "editor.formatOnSaveMode": "modifications",
+  "[scss]": {
+    "files.trimTrailingWhitespace": true,
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[js]": {
+    "files.trimTrailingWhitespace": true,
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[html]": {
+    "files.trimTrailingWhitespace": true,
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

README.md

@@ -2,7 +2,54 @@
 
 Delphi's homepage at https://cmu-delphi-main.netlify.app/
 
-This site is based on [Hugo](https://gohugo.io).
+This site is based on [Hugo](https://gohugo.io) and uses [Prettier](https://prettier.io) for formatting.
+
+## Structure
+
+The main content is in the `/content` directory written in Markdown or RMarkdown for blog posts.
+In addition to the Markdown content frontmatter with YAML syntax is used at the beginning of the file to customize and describe the content. Common fields include `title` and `description`.
+However, depending on the file it can have additional fields. For example for blog posts additional fields are used to list the authors, hero images, summaries, tags, and so on.
+
+### Linking
+
+Hugo uses so called shortcodes for embedding logic into Markdown files. A good example is linking to other pages.
+
+A relative reference to another page can be created using the `relref` shortcode. The argument is the filename with an optional `#` anchor to jump to a specific section.
+
+**Examples**
+
+```
+national daily survey]({{< relref "surveys">}})
+[syndromic COVID-19 indicator based on doctor visits]({{< relref "2020-10-14-dv-signal" >}})
+[self-reported symptoms]({{< relref "2020-08-26-fb-survey#whats-in-the-survey" >}})
+```
+
+Instead of a direct link to the API reference there is the `apiref` shortcode. The advantage is that it is easy to later change the API base URL without changing each appearance. The argument is the path segment to point to.
+
+**Examples**
+
+```
+[public API]({{< apiref "api/covidcast.html" >}})
+[Epidata API]({{< apiref "/" >}})
+```
+
+In RMarkdown things are slightly more different since the R Markdown parser is used before Hugo takes over. Blogdown has a special function for handling shortcodes: `blogdown::shortcode_html`.
+
+**Examples**
+
+```
+[Facebook](`r blogdown::shortcode_html("ref", "2020-08-26-fb-survey")`)
+[previous exploratory investigations](`r blogdown::shortcode_html("ref", "2020-08-26-fb-survey#some-interesting-examples")`)
+[public API](`r blogdown::shortcode_html("apiref", "api/covidcast.html")`)
+
+```
+
+### Data
+
+In addition, there in the `/data` directory there are the following listings in YAML syntax
+
+- `authors.yaml` list of blog authors referenced in the `authors` field in blog posts. This list is used to generated the author information at the end of a blog post
+- `supporters.yaml` list of supporters/collaborators
 
 ## Development Environment
 
@@ -13,8 +60,9 @@ This site is based on [Hugo](https://gohugo.io).
 
 #### Commands
 
-1. run `npm start` to create a development Hugo server
-1. run `npm build` to build a minified build in `/public`
+1. run `npm start` to create a development Hugo server running at http://localhost:1313
+1. run `npm run format` to run prettier and format files
+1. run `npm run build` to build a minified build in `/public`
 
 ### Blog Editor
 
@@ -38,10 +86,15 @@ In order to convert the Rmd files to HTML files for Hugo you also need to:
    - `local=TRUE` similar to `-D` to process draft files
    - `run_hugo=FALSE` to manually run hugo
    - `build_rmd=TRUE` force a (re)build of the Rmd pages
+1. Alternatively, run `npm run build:blog`
 1. Run Hugo server as usual
 
-blogdown also has an integrated server `blogdown::serve_site()` which will render RMarkdown files on the fly and does a similar thing as `hugo server -D`
+blogdown also has an integrated server `blogdown::serve_site()` which will render RMarkdown files on the fly and does a similar thing as `hugo server -D`.
+A shortcut is available through `npm run start:blog`.
 
 #### Adding a new blog post
 
 In case you use new dependencies don't forget to either edit `environment.yml` or `dependencies.R`.
+A Github action should runs when Rmd files changes so it will verify that the blog post can be built.
+However, the converted HTML file along with all generated images are committed to the repository.
+This simplifies the deployment and ensures that we have a blog post even when the API or data changes.

_output.yml

@@ -1,3 +1,3 @@
 blogdown::html_page:
   # force svglite device, since cairo is a mess
-  dev: "svglite"
+  dev: svglite