Docs reorg

[marcwitasee]

Chameleon Documentation Reorganization Summary

Overview

This document summarizes all changes made in the docs_reorg branch to improve the structure, organization, and maintainability of the Chameleon Cloud documentation.

Major Changes

1. Documentation Structure Reorganization

Technical Documentation Restructuring

The monolithic documentation files were split into modular directory structures with dedicated index pages:

Section	Changes
baremetal/	Split into launching_gui.rst, launching_cli.rst, interacting.rst
cli/	Split into installation.rst, authentication.rst, rc_script.rst, usage.rst
complex/	Split into catalog.rst, gui_management.rst, cli_management.rst, heat_templates.rst, sharing.rst, advanced_topics.rst
discovery/	Split into hardware_catalog.rst, rest_api.rst
gui/	Split into features.rst, api_access.rst, navigation.rst
images/	Split into supported_images.rst, cc_snapshot.rst, gui_management.rst, cli_management.rst
jupyter/	Added jupyter_collaboration.rst, jupyter_dedicated.rst
kvm/	Split into kvm_gui.rst, kvm_lbaas.rst, kvm_cli.rst
networks/	Split into networks_basic.rst, networks_vlan.rst, networks_stitching.rst, networks_fabnet.rst, networks_jumbo_frames.rst
power_monitoring/	Created dedicated directory with index.rst
reservations/	Split into gui_reservations.rst, cli_reservations.rst
shares/	Split into concepts.rst, gui_management.rst, cli_management.rst, mounting.rst
sharing/	Split into browsing_artifacts.rst, packaging_artifacts.rst (Trovi)
swift/	Split into swift_gui.rst, swift_cli.rst, swift_mount.rst

Backwards Compatibility

• Created redirect pages at old file locations using :orphan: directive and meta refresh tags
• Ensures existing links continue to work while guiding users to new locations

Cross-Reference Updates

• Updated all internal document references to point to new locations
• Modified contents.rst and technical/index.rst toctree directives
• Fixed image paths to work from new directory locations

2. Content Improvements

Technical Overview Updates

• Added Trovi Sharing Portal and Daypass sections to technical guide
• Improved descriptions for each technical section
• Better organized content in technical/index.rst

Getting Started Guide

• Removed detailed login information, moved to federation.rst
• Streamlined content to focus on core workflow
• Updated PI references throughout
• Removed redundant content

User Documentation

• Enhanced federation page with comprehensive authentication information
• Replaced mailing list references with community forum
• Updated PI eligibility documentation
• Improved clarity and organization

Home Page Refresh

• Reorganized main index page with clearer structure
• Added distinct sections for features and quick navigation
• Improved content readability

3. Documentation Standards

Header Capitalization Standards

Established consistent header formatting across all documentation:

• Page titles (double underline ===): Title Case
• H1 headers (single underline ===): Title Case
• H2+ headers (underline ---, ~~~, ^^^): Sentence case

Structural Fixes

• Corrected header hierarchy in getting-started/index.rst
• Fixed misclassified headers using wrong underline characters
• Standardized toctree captions across technical sections
• Reduced toctree maxdepth from 5 to 2 for better navigation

4. User Experience Improvements

Feedback Channel

• Added feedback box to documentation pages
• Included GitHub issue link for reporting problems
• Encouraged user contributions

Fixed Issues

• Typo corrections:
  • "Reseving" → "Reserving"
  • "Reserverving" → "Reserving"
• GUI section image styling fixes
• Streamlined GUI documentation for clarity

5. Content Cleanup

• Removed outdated software-defined networking documentation
• Cleaned up obsolete references
• Eliminated content duplication

Impact Summary

• 116 files changed
• 5,370 insertions, 5,751 deletions
• Net reduction in lines due to better organization
• Improved modularity and maintainability
• Better separation of GUI/CLI documentation
• Enhanced user navigation experience

Commit History

Key commits in chronological order:

1. 822d6ff - Fix technical overview table of contents
2. 256bf12 - Reorganize the documentation structure
3. bada40d - Reorganize more technical documentation
4. 667191e - Update shares directory structure
5. b0fbdaf - Implement feedback channel for documentation
6. b489592 - Fix content headings on technical pages
7. 94c8f5f - Standardize header names in documentation

[Mark-Powers]

Overall looks good. A few concerns

• The create issue link doesn't work for me. I submitted another PR we can merge into this in #136
• We'll have to corresponding update #124 to conform to this organization
• Can you check on the .github/CODEOWNERS file? It doesn't seem to be working. Ideally the users in the file are notified when an issue or PR is created based on that, which would be useful if users are submiting those.

[marcwitasee]

@Mark-Powers is there any thing else? I am not sure what to do with the CODEOWNERS file.