HyP3 documentation is built using MkDocs and the ASF Theme.
In order to automatically document some of our APIs, we use a conda environment
with our APIs installed. You can get Miniconda (recommended) here:
https://docs.conda.io/en/latest/miniconda.html
Once conda is installed, from the repository root, you can create and activate a conda environment with all the necessary dependencies
conda env create -f environment.yml
conda activate hyp3-docs
Later, you can update the environment's dependencies with
conda env update -f environment.yml
With the hyp3-docs conda environment activated, run
mkdocs serve
to generate the documentation. This will allow you to view it at http://127.0.0.1:8000/. MkDocs will automatically watch for new/changed files in this directory and rebuild the website so you can see your changes live (just refresh the webpage!).
Note: mkdocs serve captures your terminal; use crtl+c to exit. It is recommended you
use a second/dedicated terminal so you can keep this command running.
This documentation site is deployed as a GitHub Organization website with a CNAME
so that it's viewable at https://hyp3-docs.asf.alaska.edu/. The website is served
out of the special https://github.com/ASFHyP3/ASFHyP3.github.io repository. Deployment
is handled automatically with the .github/workflows/deploy_to_github_io.yml GitHub
Action for any merge to main.
There is also a test site deployed to https://hyp3-docs.asf.alaska.edu/hyp3-docs, which
tracks the develop branch of this repo and is served out of the gh-pages branch
of this repo.
We can display a site-wide banner for important announcements.
The content of this banner is specified in overrides/main.html,
which should contain the following placeholder text when the banner is not in use:
{% extends "partials/main.html" %}
{# Uncomment this block to enable the announcement banner:
{% block announce %}
<div id="announcement-content">
⚠️ TODO: Your announcement here.<br />
<a class="announcement-link" href="TODO">Read the full announcement.</a>
</div>
{% endblock %}
#}In order to enable the banner, uncomment the announce block and fill in the TODOs.
Below is an example of an enabled announcement banner
(taken from here):
{% extends "partials/main.html" %}
{% block announce %}
<div id="announcement-content">
⚠️ Monthly processing quotas were replaced by a credit system on April 1st.<br />
<a class="announcement-link" href="/using/credits">Read the full announcement.</a>
</div>
{% endblock %}When the announcement is no longer needed, restore the file to the placeholder text in order to disable the banner.
If you are building and viewing the site locally,
you will need to exit with ctrl+c and then re-run mkdocs serve
in order to re-render any changes you make to this file.
The way MkDocs and GitHub parse the markdown documents are slightly different. Some compatibility tips:
-
Raw links should be wrapped in angle brackets:
<https://example.com> -
MkDocs is pickier about whitespace between types (e.g., headers, paragraphs, lists) and seems to expect indents to be 4 spaces. So to get a representation like:
-
A list item
- A sub-list item
in MkDocs, you'll want to write it like:
- A list item ##### A sub list heading - A sub-list item- A list item ##### A sub list heading - A sub-list item- A list item ##### A sub list heading - A sub-list item- A list item ##### A sub list heading - A sub-list item -
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent