Contributing to CADES User Documentation

Would you like to make things better? There are a few ways you can contribute to improving our documentation and adding user-created tutorials or content.

Email your suggestions to the team cades-help@ornl.gov
Join our community on Slack! It's friendly. http://cades.slack.com
Submit a merge request to our User Documentation repository. We have made a note of a few things to keep in mind while creating user content. You can find them in our authoring guide.

About CADES User Documentation

The CADES User Documentation web pages are created using MkDocs. MkDocs uses the Python Markdown library to translate Markdown files located in the docs directory to HTML. The Python Markdown supports a variety of extensions that customize how pages are formatted.

In addition to the translation process, the MkDocs binary includes a built in development server that can be used on your local system to preview how the documentation looks as well as other useful information related to the structure of the navigation and links to other pages within the site.

The theme used for the CADES User Documentation web site is the Grist Labs mkdocs-windmill theme.

Some of the Python Markdown extensions are enabled in the repository. Please review the the Authoring Guide for CADES for which are enabled. The Authoring Guide markdown document also demonstrates the use of each enabled extension.

The remainder of this page will be a walk through of setting up a system for development. For details on how the content should be formatted, please see the Authoring Guide for CADES document.

Note

This guide assumes that the development system has git installed as well as Python3. If either are missing, you will note be able to do development work as shown below.

Installation of MkDocs

To setup for development, create a python3 virtual environment. Then, the following components need to be installed using pip:

Markdown
markdown-include
mkdocs
mkdocs-windmill

This may be accomplished using the requirement.txt file provided in the root of the cadesops-userdocs repository using the command pip install -r requirements.txt, individually, or using the command pip install mkdocs mkdocs-windmill markdown-include.

Setup Examples

Setup on Mac OS

For a demonstration of setting up MkDocs on Mac OS:

Note

The demonstration requires that you are on the ORNL network directly or through the VPN. If you are not, the session is available here as well.

Markdown Editors

The mkdocs content generator is agnostic as to which editor to use. Some that have been known to be used in markdown editing: vim, vscode, typora, and atom. As long as mkdocs can generate valid content from the markdown created by the code, the choice of editor is left to the preference of the user.

Site Configuration File

The site is configured entirely in a single configuration file: mkdocs.yml. it begins with the global configuration:

site_name: CADES User Documentation
site_url: https://docs-test.cades.ornl.gov/
repo_url: https://code-int.ornl.gov/cades-puppet/user-documentation
repo_name: GitLab

extra:
  logo: img/logo.png
  article_nav_top: false

markdown_extensions:
  - admonition
  - footnotes
  - markdown_include.include:
      base_path: docs
  - tables
  - toc

theme:
  name: windmill

These settings configure the title of the site, the base URL for the website, the URL of the code repository, the CADES logo, markdown extensions for use, and the theme to be mkdocs-windmill. Additionally, it removes the Previous/Next navigation buttons at the top of the pages that would normally be present by the mkdocs-windmill theme.

After the global site setup, navigation is configured:

nav:
  - 'CADES User Documentation': README.md
  - 'CADES Support':
    - 'Cades User Charter': user-charter.md
    - 'Request Forms': 'https://cades.ornl.gov/special-request-forms/'
    - 'Support':
      - 'Getting Help': SUPPORT.md
      - 'CADES Team Members': MEMBERS.md
      - 'CADES Acknowledgement': acknowledge.md
    - 'XCAMS External Access': external-access.md
    - 'UCAMS External Access': external-access-ucams.md
  - 'Quick-Start Guides':
    - 'Storage Solutions: Quick-Start': quick-starts/storage-quick-start.md
    - 'Launch a VM Instance: Quick-Start': quick-starts/launch-vm-quick-start.md
    - 'SHPC Condos: Quick-Start': quick-starts/condo-quick-start.md
    - 'CADES Cheatsheet': quick-starts/cades-cheatsheet.md
  - 'CADES Cloud User Guide':
    - 'Overview':
      - 'Cloud Overview': openstack/about/cloud-overview.md
...

Development Workflow

The following overall workflow is used:

Create branch from main
Develop locally with mkdocs virtual environment
Push branch to GitLab
Create a merge request. If you do not have permission to merge, please request assistance.
Deactivate the virtual environment

Create Branch from Main

This would look similar to:

millerjl-laptop:userdocs 33m$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.
millerjl-laptop:userdocs 33m$ git pull
Already up to date.
millerjl-laptop:userdocs 33m$ git checkout -b 33m_newdevbranch
Switched to a new branch '33m_newdevbranch'
millerjl-laptop:userdocs 33m$ git status
On branch 33m_newdevbranch
nothing to commit, working tree clean

The UID in front is a short convention to quickly show who is primarily working on the content for the branch.

Local Development

The use of mkdocs allows for development locally. The mkdocs binary provides the ability (mkdocs serve command) to build and launch a web server on the developers systems to preview how the site would look once the markdown is generated into HTML. While the web server is running, saves to docs files are automatically detected regenerating the content that changed and (if necessary) refreshing the content in the web broswer.

The output of the mkdocs serve command indicates the health of a repository for the mkdocs build process. The following indicates a clean startup of the web server:

(mkdocs) millerjl-laptop:admindocs 33m$ mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
INFO    -  Documentation built in 1.05 seconds 
[I 200909 08:17:35 server:334] Serving on http://127.0.0.1:8000
INFO    -  Serving on http://127.0.0.1:8000
[I 200909 08:17:35 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 200909 08:17:35 handlers:64] Start detecting changes
INFO    -  Start detecting changes

As can be seen, the mkdocs binary builds the documentation into a site directory and then serves the documenation to the loopback interface on port 8000. Opening a web browser, one navigates to the listed URL to view the documentation in it's current state.

Upon startup and while editing files, the mkdocs serve command will also log conditions that exist in the repository during the build process that may be of concern. For example, the following result:

INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - SUMMARY.md
  - cheatsheet/README.md
  - condos/how-to-use/access-shpc.md
  - condos/how-to-use/how-to-use.md
  - condos/how-to-use/prerequisites.md
  - condos/how-to-use/request-access.md
  - condos/how-to-use/resource-queues.md
  - condos/how-to-use/examples/cpp.md
  - condos/how-to-use/examples/fortran.md
  - condos/how-to-use/examples/makefile.md
  - condos/how-to-use/examples/python.md
  - condos/slurm/execute-a-slurm-job.md
  - condos/slurm/openacc-tutorial.md
  - condos/slurm/slurm-migration.md
  - condos/slurm/slurm-resource-queues.md
  - condos/software/gnu-compiler.md
  - condos/software/intel-compiler.md
  - condos/software/scheduling-jobs.md
  - condos/templates/slurm-migration-alert-alternate.md
  - condos/templates/slurm-migration-alert.md
  - contributing/legacy/git-command-line-legacy.md
  - contributing/legacy/git-workflow-legacy.md
  - more-tools/putty-smartcard-auth.md
  - openstack/manage-vm/Transferring-Volume.md
  - user-contributed-tutorials/aws-tutorials/aws-index.md
  - user-contributed-tutorials/aws-tutorials/aws-tips.md
  - user-contributed-tutorials/aws-tutorials/aws-training.md
  - user-contributed-tutorials/aws-tutorials/ec2/ec2-describe-instances.md
  - user-contributed-tutorials/aws-tutorials/ec2/ec2-index.md
  - user-contributed-tutorials/aws-tutorials/ec2/ec2-launch-instance.md
  - user-contributed-tutorials/aws-tutorials/iam/aws-account-creation.md
  - user-contributed-tutorials/aws-tutorials/iam/aws-iam-overview.md
  - user-contributed-tutorials/aws-tutorials/object-storage/s3-index.md 
WARNING -  Documentation file 'SUMMARY.md' contains a link to 'condos/how-to-use/running-jobs.md' which is not found in the documentation files. 
WARNING -  A relative path to 'condos/how-to-use/running-jobs.md' is included in the 'nav' configuration, which is not found in the documentation files 
WARNING -  Documentation file 'condos/how-to-use/execute-a-slurm-job.md' contains a link to 'condos/how-to-use/running-jobs.md' which is not found in the documentation files. 
INFO    -  Documentation built in 2.40 seconds

The INFO message The following pages exist in the docs directory, but are not included in the "nav" configuration may or may not be of concern. It is possible that there are documents that are referenced in other pages that are not desired to be on the main navigation bar in order to keep it clean. If there is a page that should be referenced in the navigation, the mkdocs.yml file should be modified to add it.

The WARNING message Documentation file XXXXX contains a link to XXXXXX which is not found in the documentation files references a broken link within a document to another page. This could be for a variety of reasons: page exists but referenced incorrectly, page doesn't exist but will soon, page was accidentally removed, etc.

The WARNING message A relative path to XXXXX is included in the 'nav' configuration, which is not found in the documentation files indicates a navigation link that is broken and needs to be addressed. This could be for a variety of reasons: page exists but referenced incorrectly, page doesn't exist but will soon, page was accidentally removed, etc.

Push branch to GitLab

As needed, commit and push changes up to the remote branch for collaboration with others or in preparation for merge to main:

millerjl-laptop:userdocs 33m$ git commit -a -m "mkdocs_HOWTO: add local dev section"
[33m_howto 5f885e7b] mkdocs_HOWTO: add local dev section
 1 file changed, 68 insertions(+)
millerjl-laptop:userdocs 33m$ git push origin 33m_howto
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 1.74 KiB | 1.74 MiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: 
remote: To create a merge request for 33m_howto, visit:
remote:   https://code-int.ornl.gov/cades-ops/userdocs/-/merge_requests/new?merge_request%5Bsource_branch%5D=33m_howto
remote: 
To code-int.ornl.gov:cades-ops/userdocs.git
   c13a50e1..5f885e7b  33m_howto -> 33m_howto

Create a Merge Request

When a branch is pushed up to GitLab, the output of the operation provides a URL that may be used to create the merge request. If all changes are done, click the "Submit Merge Request" button at that URL to start the process. If you do not have permission to merge your own request to the main branch, please request assistance.

Deactivate Virtual Environment

When development work is completed, one could deactivate the Python 3 virtual environment:

^C[I 200918 08:19:58 server:358] Shutting down...
INFO    -  Shutting down...
(mkdocs) millerjl-laptop:userdocs 33m$ deactivate
millerjl-laptop:userdocs 33m$

returning your shell back to normal.