Colorado's Decision Support Systems (CDSS) learning resources for Git
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github
build-util
mkdocs-project
.gitattributes
.gitignore
README.md

README.md

cdss-learn-git

Colorado's Decision Support Systems (CDSS) Git/GitHub training.

Introduction

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 mkdocs-project folder. 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.

Prerequisites

The following software must be installed to view the documentation with MkDocs:

How to Edit/View/Deploy

  1. To view: Run mkdocs serve on the command line in the mkdocs-project folder. Then view in a browser using address http://localhost:8000 (link will only work if the site is being served locally).
  2. 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.
  3. To deploy: Run the build-util/copy-to-owf-amazon-s3.sh shell script or build-util/copy-to-owf-amazon-s3.bat Windows 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.

Contributing

Contributions can be made via normal Git/GitHub protocols:

  1. Those with commit permissions can make changes to the repository.
  2. Use GitHub Issues to suggest changes (preferred for small changes).
  3. Fork the repository and use pull requests.

Credits

Maintainers:

  • Steve Malers, Open Water Foundation (@smalers)

License

The license is being determined as part of the OpenCDSS effort. CC BY 4.0 has been recommended.

Release Notes

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