CU Library Read the Docs

ReadtheDocs is CU Boulder Libraries Core Tech & Apps approved method for documentation.

1. Github Markdown Guides

2. Read the Docs Documentation

Requirements

1. Python 3.3 or greater

Installation

1. Clone Repository

   git clone git@github.com:culibraries/documentation.git
   
   or
   
   git clone https://github.com/culibraries/documentation.git
   

2. Create Virtual Environment

   NOTE: Win variations assume cmd.exe shell

   cd documentation
   python3 -m venv venv (Win: python -m venv <dir>)
   . venv/bin/activate (Win: venv\Scripts\activate.bat)
   pip install -r requirements.txt
   

3. Create HTML

   cd docs
   make html
   

4. New Terminal - Web server

   . venv/bin/activate
   cd docs/_build/html
   python -m http.server
   Serving HTTP on :: port 8000 (http://[::]:8000/) ...
   

5. Open Browser http://localhost:8000

Add new documentation

1. git checkout -b new_docs

2. Edit/Add documentation (Markdown)

3. make html

4. add new pages to toctree (index.rst)

Pull Request to main branch

CU Boulder Libraries’ regular activity is to create a PR from the release branch with a code review. The documentation repository is slightly different. Perform a PR from the feature branch to the main branch. Add a code review before merge to main.

View Build Process on ReadtheDocs

1. Merge to main required before ReadtheDocs build process will start.

2. ReadtheDocs View builds

3. After successful build: https://cu-boulder-libraries.readthedocs.io/en/latest/