Add content#

As the project expands there is a need to expand the documentation with it. This page will go over how to add content to this documentation site and publish those changes.

Clone GitHub Repo#

All content is stored in a GitHub repository where changes can be tracked. Updates to the contents of the repository automatically update the GitHub Pages instance and a Pull Request is created to update the applications Helm chart in the main branch. Any updates to the documentation site start by creating a copy of the code locally and changing in to the docs directory.

git clone https://github.com/NCAR/cisl-cloud.git
git checkout -b docs

Add new notebooks#

Create new notebooks that contain the content that needs to be shared with the user base. Right now there are a few different folders to store these documents. Here is a breakdown of what folders are and the content they host:

_static/            # Place any images, custom css, or javascript here
_templates/         # Custom HTML pages to overwrite the templates used by Project Pythia
availability/       # Content related to available services and hardware 
how-to/             # All How-To do content
    2i2cJH/         # Any information relating to use of the 2i2c hosted JupyterHub
    binderhub/      # How-to use the BinderHub instance
    data-access/    # Information on accessing different data locations using varying methods
    jupyter-book/   # Details about this documentation website and how to maintain
    K8s/            # General kubernetes information
    k8sJH/          # Information relating directly to the use of the NCAR JupyterHub running on k8s
    sops-age/       # Configuring OPS and age encryption for use in GitHub to protect sensitive information
    Stratus/        # How-to utilize Stratus for object storage
    vm/             # Brief intro to VMs and how to get one
images/             # Only used for the navbar icon and favicon.
overview/           # General information about the project and services
slas/               # Service Level Agreement policies

Note

Place any images used in notebooks directly in the _static/ directory and reference them using a URL like https://ncar.github.io/cisl-cloud/_static/my-new-image.png. Images placed in the images directory are not copied correctly.

When adding content please place the files in a directory that makes sense. If one does not exist please create a directory for it that is descriptive for others.

Note

Any new additions should also be reflected by updating the directory layout above.

Update _toc.yml#

Note

The JupyterBook Documentation is a good reference for the table of contents structure.

Just adding content is not enough to actually publish it on the site. Any new additions need to be reflected in the _toc.yml (Table of Contents) file. Below is a short example of the _toc.yml file that covers the applicable layouts:

format: jb-book
root: index
parts:
  - chapters:
    - file: overview/about
    - file: overview/use-cases
    - file: overview/goals
  - caption: How-Tos 
    chapters:
      - title: Agile Interaction
        file: how-to/agile
      - title: Jupyter Book
        file: how-to/jupyter-book/jb-intro
        sections:
          - file: how-to/jupyter-book/create-jb

The top line defines the format that Jupyter Book should expect from the table of contents. jb-book specifies that Jupyter Book should expect chapters and parts in the rest of the file.

The second line defines the homepage or root file that should be loaded. For this documentation the index.ipynb file is specified to be the root.

Note

File extensions are not required when specifying any of the files to load. For this reason be careful not to duplicate filenames with different file extensions.

The final main section of the yaml file we are using is for parts. This is where all the different content is laid out and organized. There’s a few different ways to outline all of this, as shown in the above layout, and we will cover each one.

The most straightforward way to display content is by pairing the chapters entry with the file entry.

Build and test updates#

Once all the changes are in place it’s time to build the new book and test it locally. This procedure is already outlined at this link to building HTML files. Please use that documentation to build, test, push, and deploy the changes made to the documentation.

Push changes#

There are CICD jobs configured in the cisl-cloud GitHub repository that will automatically update the GitHub pages hosted page and create a Pull Request to update the K8s hosted versions Helm chart with a new container image.

On this page