Colorado's Decision Support Systems (CDSS) Git/GitHub training.
This repository contains the source content of a MkDocs static website for CDSS Git/GitHub training. The training lessons that are encapsulated in this repository are intended to provide introductory Git training for those who have never before used Git (perhaps have not use version control at any level). Advanced topics are also included in order to provide a CDSS perspective on version control and Git. This documentation serves as a reference for all CDSS development.
MkDocs is used because it allows training materials to be created using Markdown, content can be easily managed in Git/GitHub, and the resulting static website is professional-looking, navigable, and useful.
Repository Folder Structure
The repository contains a typical MkDocs project in the
Refer to MkDocs documentation for guidance on creating MkDocs websites.
cdss-learn-git/ Git repository folder matching repository name. build-util/ Folder containing useful scripts. mkdocs-project/ Folder containing standard MkDocs project. docs/ Folder containing Markdown files. mkdocs.yml Configuration file for the documentation. site/ Static website, dynamically created and in .gitignore. README.md This file.
Development Environment Folder Structure
The following folder structure is recommended for the development environment for this documentation.
C:\Users\user\ Windows user folder. /c/Users/user/ Git Bash user folder. cdss-dev/ Development files for OpenCDSS products. Learn-Git/ Product folder for this documentation. git-repos/ Git reposities for the documentation (only one needed, below). cdss-learn-git/ The repository files as shown in the previous section.
The following software must be installed to view the documentation with MkDocs:
How to Edit/View/Deploy
- To view: Run
mkdocs serveon the command line in the
mkdocs-projectfolder. Then view in a browser using address http://localhost:8000 (link will only work if the site is being served locally).
- To edit: Use a text editor. The web browser content will automatically refresh when changes are detected. If the browser does not load content, it is usually because there is an error, and a message will be printed in the command line window.
- To deploy: Run the
build-util/copy-to-owf-amazon-s3.shshell script or
build-util/copy-to-owf-amazon-s3.batWindows batch file to copy to OWF cloud static website. This will require appropriate credentials for the receiving cloud system. An alternate script will be added to copy to a CDSS/State of CO website in the future.
Contributions can be made via normal Git/GitHub protocols:
- Those with commit permissions can make changes to the repository.
- Use GitHub Issues to suggest changes (preferred for small changes).
- Fork the repository and use pull requests.
- Steve Malers, Open Water Foundation (@smalers)
The license is being determined as part of the OpenCDSS effort. CC BY 4.0 has been recommended.
The following release notes indicate the update history for documentation, with GitHub repository issue indicated, if applicable (links to issues via README.md are not cleanly supported by GitHub so use the repository issues page to find).
- 2017-10-23 [2,3,4,5,8,12,14] - switch to Material theme, fill out content for additional pages, fix some broken links
- 2017-10-01 - initial version