Documentation Guide

Canvas CLI Documentation Guidelines

Overview

This document outlines the documentation standards for the Canvas CLI project, covering both in-code documentation and external documentation. Following these guidelines ensures consistency and helps maintain high-quality, accessible documentation.

Documentation Structure

canvas-cli/
  ├── canvas_cli/               # Source code with in-code documentation
  ├── docs/                     # Documentation directory
  │   ├── testing_guide.md      # Guide for running and writing tests
  │   ├── documentation.md      # This file - documentation standards
  │   └── learning.md           # Things I learned while working on this project
  ├── tests/                    # Tests directory
  └── README.md                 # Project overview and quick start

In-Code Documentation

Module Docstrings

Each Python module should begin with a docstring that explains its purpose:

"""
Canvas API module
Handles communication with the Canvas REST API
"""

Class Docstrings

Every class should have a docstring explaining its purpose and functionality:

class CanvasAPI:
    """Main class for interacting with the Canvas API
    
    This class provides methods to communicate with the Canvas LMS API,
    handling authentication, requests, and response parsing.
    """

Function/Method Docstrings

Document all functions and methods using the following format:

def submit_assignment(course_id, assignment_id, file_path):
    """Submit an assignment file to Canvas
    
    Args:
        course_id (int): The Canvas course ID
        assignment_id (int): The Canvas assignment ID
        file_path (str): Path to the file to submit
        
    Returns:
        dict: The submission response from Canvas
        
    Raises:
        ValueError: If the file doesn't exist or can't be read
        RequestException: If the API request fails
    """

Code Comments

Use comments to explain complex logic, workarounds, or non-obvious decisions:

# Use a fallback method for Windows systems where curses is not available
if not CURSES_AVAILABLE:
    return text_select_course_and_assignment()

TODOs

Mark incomplete functionality with TODO comments that include context:

# TODO: Add support for quiz submissions (waiting for API endpoint documentation)

External Documentation

README.md

The project README should include:

• Brief project description
• Installation instructions
• Quick start guide
• Basic usage examples
• Links to more detailed documentation

Feature Documentation

For each major feature, provide:

1. Overview of what the feature does
2. Command syntax and options
3. Example usages
4. Common issues and solutions

Example:

## Clone Command

The `clone` command downloads assignment descriptions and related files from Canvas.

### Basic Usage

`canvas clone -cid 12345 -aid 67890`

### Options

- `-cid, --course_id` - Canvas course ID
- `-aid, --assignment_id` - Canvas assignment ID
- `-o, --output` - Output filename (default: README.md)
- `-pdf` - Download linked PDFs
- `-cdl, --convert_links` - Add clean download links

API Documentation

Canvas API Endpoints

Endpoint	Method	Description	Parameters	Returns
/courses	GET	Lists all active courses for the current user	enrollment_state=active, include[]=favorites, per_page=100	Array of course objects sorted by favorite status and name
/courses/{course_id}	GET	Gets detailed information about a specific course	Optional properties in params	Course object with details
/courses/{course_id}/assignments	GET	Lists all assignments for a specific course	per_page=100	Array of assignment objects sorted by status and due date
/courses/{course_id}/assignments/{assignment_id}	GET	Gets detailed information about a specific assignment	None	Assignment object with details
/courses/{course_id}/assignments/{assignment_id}/submissions/self	GET	Gets the current user's submission for a specific assignment	None	Submission object with details
/courses/{course_id}/assignments/{assignment_id}/submissions/self/files	POST	Initiates file upload for assignment submission	name, size, content_type, on_duplicate	Upload URL and parameters
{upload_url from previous response}	POST	Uploads file data to specified URL	Upload parameters from previous response	File ID and other file details
/courses/{course_id}/assignments/{assignment_id}/submissions	POST	Submits an assignment with uploaded file(s)	submission_type, file_ids	Submission confirmation

API Parameters Details

GET /courses

• enrollment_state=active: Filters courses by enrollment state
• include[]=favorites: Includes information about whether courses are favorited
• per_page=100: Limits results to 100 courses per page

POST /courses/{course_id}/assignments/{assignment_id}/submissions/self/files

• name: Filename of the submission
• size: Size in bytes of the file
• content_type: MIME type of the file (default: "application/octet-stream")
• on_duplicate: Action to take if file already exists (default: "overwrite")

POST /courses/{course_id}/assignments/{assignment_id}/submissions

• submission_type: Type of submission (e.g., "online_upload")
• file_ids: Array of file IDs to include in the submission

Authentication

All API requests require an authentication token provided in the Authorization header:

Authorization: Bearer {token}

Response Handling

The application handles API responses by:

1. Sorting and filtering results for better usability
2. Error handling with detailed error messages
3. Converting date strings to readable format

Maintaining Documentation

When to Update

Documentation should be updated when:

1. Adding a new feature
2. Changing existing functionality
3. Fixing bugs that affect user experience
4. Improving or clarifying existing documentation

Documentation Review Checklist

Before submitting changes, ensure:

• All new functionality is documented
• Affected existing documentation is updated
• Code examples are accurate and tested
• Spelling and grammar are correct
• Formatting is consistent

Documentation Tools

Consider using these tools to enhance documentation:

1. Sphinx - For generating comprehensive HTML documentation
2. mkdocs - For simple, readable documentation sites
3. doctest - For testing code examples in docstrings

Docstring Style Guide

We use Google-style docstrings for consistency:

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.
    
    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.
    
    Returns:
        bool: The return value. True for success, False otherwise.
    """