How to contribute to this documentation

This page describes how to contribute to this web documentation. The underlying text is written in Markdown as a source code, which is converted to html, css, and java script languages and construct the website. The website is made accessible through the NERSC Science gateway service.

The source code is maintained under the WACCEM Github repository "pinacles_doc", although currently it is not open to the public yet. Please contact Koichi Sakaguchi to join the project.

Required libraries

The source code should be cloned from the WACCEM repository, and create your own local branch:

$git clone git@github.com:WACCEM/pinacles_docs.git
$cd pinacles_docs
$git branch [your local branch name] # create a local branch as a copy of the main branch
$git push -u origin [your local branch name] #create a remote branch in the Github repo

Very helpful Markdown reference is the markdownguide.org. The basics and some of the extended syntax should be sufficient for this documentation; we just give up anything we cannot do with those basics.

After uploading your changes to the remote branch of your own, you can create a merge request to bring the changes into the main branch, which will then be included in the web document.

In order to do lint checks and construct the website, we need the following libraries (following the NERSC documentation).

One can install the dependent libraries as python conda packages as a conda environment named "docs" by using the docs_mkdown.yml file in the top directory of the source code.

$conda env create -f docs_mkdown.yml
$conda activate docs

Then for checking the code quality & best practices (lint checks), we run the linter markdownlint on the docs/ directory.

$markdownlint docs

This will give a list of not-so-good practices and errors.

One can run the script build_site.sh to construct the website, but the pathnames are hard-coded to the WACCEM project directory, hence it should be left for the maintainers. To get an idea of how the rendered text look like, a simpler way is to use a Markdown editor, more a general editor like VScode. VScode can show us a preview as a separate tab, for example.