Skip to content

Latest commit

 

History

History
184 lines (124 loc) · 8.8 KB

README.md

File metadata and controls

184 lines (124 loc) · 8.8 KB
Raw

Spell check YAML check MarkdownLint Markdown URLs ShellCheck Odds and Ends

The Wynton HPC Website

This repository contains the Wynton HPC website https://wynton.ucsf.edu/hpc/. Updates to the 'master' branch will be published and go live within minutes. There is also a near-live GitHub Pages mirror at https://ucsf-wynton.github.io/wynton-website-hpc/.

Dynamically generated data

The website provides dynamic summaries of data that are produced on regular basis by crontab jobs. Below are some of the data files used:

Prototype the website locally

To get a local copy of this repos, do:

$ cd /path/to/my/repositories
$ git clone https://github.com/ucsf-wynton/wynton-website-hpc.git
$ cd wynton
$ pwd
/path/to/my/repositories/wynton

To launch a localhost instance of the website, do:

$ ## Make sure to have 'bundle' on the PATH, e.g.
$ ## export PATH="$HOME/.gem/ruby/2.5.0/bin:$PATH"

$ cd docs
$ bundle exec jekyll serve --port 4001
Configuration file: /home/alice/wynton/docs/_config.yml
            Source: /home/alice/wynton/docs
       Destination: /home/alice/wynton/docs/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 0.94 seconds.
 Auto-regeneration: enabled for '/home/alice/wynton/docs'
    Server address: http://127.0.0.1:4001
  Server running... press ctrl-c to stop.

and then open http://127.0.0.1:4001 in the web browser. Note that Jekyll monitors all files and if one of them is updated, then Jekyll will instantaneously re-render the corresponding HTML file. There is no need to relaunch Jekyll or by other means manually re-render files. For instance, if there has been updates made to the git repository, doing:

$ git pull

will pull down those updates locally and Jekyll will automatically re-render the HTML website.

Spell checking

$ make spell
No spelling errors found.

This requires R and that the spelling R package is installed, e.g. install.packages("spelling", repos="https://cloud.r-project.org"). If there are words that are incorrectly flagged as misspelled, they can be added to the docs/WORDLIST file.

Linting

To validate the Markdown syntax and that we follow a consistent style, run:

$ make markdownlint
*** markdownlint:
[ OK ] checking ./assets/README.md
[ OK ] checking ./about/specs.md
...
[ OK ] checking ./index.md
RESULT: 50 OK, 0 ERROR

If there are errors, the explanation for them can be found on https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md. The online markdownlint demo can be useful to better understand certain errors.

Several of the rules are disabled in the docs/.markdownlint.json configuration file.

To run these tests locally, install markdownlint-cli.

To validate the Markdown URLs exists, run:

$ make markdown-link-check
*** markdown-link-check:
[ OK ] checking ./assets/README.md
[ OK ] checking ./about/specs.md
...
[ OK ] checking ./index.md
RESULT: 50 OK, 0 ERROR

To run these tests locally, install markdown-link-check.

Technical details

This website is built upon Jekyll, where content is mostly written in Markdown and rendered by Jekyll into HTML. The user interface and its style is handled mainly by JavaScript and CSS.

Installing Jekyll

Warning: It turns out that the most recent version of Jekyll is not compatible with the recent version of GitHub Pages. Specifically, GitHub Pages requires Jekyll version >= 3.7.3 and < 4.0.0 - the latest version verified to work is Jekyll 3.8.7. So we need to make sure to install specific version of a few packages below.

The below instructions assumes that Ruby and its gem command is available on the machine. Other than that, making sure to use option --user-install when installing, you should be able install Jekyll to your personal account without admin rights.

$ gem install --user-install bundler jekyll:3.8.7 listen:3.1.5 liquid:4.0.0 github-pages:204
Fetching: bundler-2.1.4.gem (100%)
WARNING:  You don't have /home/alice/.gem/ruby/2.5.0/bin in your PATH,
          gem executables will not run.
Successfully installed bundler-2.1.4
Parsing documentation for bundler-2.1.4
Installing ri documentation for bundler-2.1.4
...
Installing ri documentation for liquid-4.0.0
Done installing documentation for liquid after 1 seconds
48 gems installed

That's it.

You then need to prepend $HOME/.gem/ruby/2.5.0/bin to your PATH such that the bundler command in that folder is automatically found;

$ export PATH="$HOME/.gem/ruby/2.5.0/bin:$PATH"
$ which bundle
/home/alice/.gem/ruby/2.5.0/bin/bundle

Set that PATH in your ~/.bashrc startup file to make it apply automatically.

That's it. You can now launch the website locally as above.

Wynton maintenance tasks

The website is hosted on an web server called wynton-web. Whenever that server is rebooted, one has to manually log in to account www-jekyll and run:

[www-jekyll@wynton-web ~]$ make restart

This will launch two proxy Jekyll servers that hosts the status graphs, etc.

Licenses