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 email@example.com
- 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.
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:
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 on Mac OS
For a demonstration of setting up MkDocs on Mac OS:
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.
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 ...
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.
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.