Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .claude/commands/test.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
Run the full Sphinx documentation build and test suite using `./run_tests.sh` (or a specific project if one is provided as an argument, e.g. `/test en_us/course_authors/`).

Identify an appropriate virtualenv and source it before running. If an appropriate virtualenv is not found, be sure to prompt the user to either select / enter an appropriate virtualenv, create a new virtualenv, or have you install the requirements globally (not advised) before running.

After the build completes:

1. Report the total Sphinx error and warning counts clearly to the user.
2. Read the `test_root/<project>/err.log` files for any project that failed to get the full warning/error detail.
3. If there are **no errors or warnings**, confirm the build is clean and ready to push.
4. If there **are** errors or warnings:
- List each one with its file path and line number.
- For each issue, either:
- **Fix it automatically** if it is straightforward (e.g. title overline too short, trailing whitespace, malformed RST directives), then re-run the tests to confirm the fix works.
- **Explain how to fix it manually** if it requires editorial judgment (e.g. broken cross-references pointing to missing content, ambiguous section structure).
- After attempting all auto-fixes, re-run the tests and report the final result.
61 changes: 61 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Status

This is an organizational fork of the upstream edx-documentation repository. While the upstream is deprecated, this fork is actively maintained to keep documentation up to date for our organization.

## Common Commands

```bash
# Install Python dependencies
make requirements

# Build all documentation projects (runs tests)
./run_tests.sh

# Build a single documentation project
./run_tests.sh en_us/developers/

# Start live-reload development server for a project
pip install -r shared/tools.txt
./develop.sh en_us/developers/ [port] # Default port: 9090

# Update/recompile Python requirements
make upgrade

# Clean build artifacts
make clean

# Create translation files for Transifex
make i18n
```

## Architecture

This is a **Sphinx-based static documentation site** using reStructuredText (RST) source files. There is no application code β€” only documentation content and build configuration.

**Technology stack:**
- Markup: reStructuredText (RST)
- Build: Sphinx with `sphinx-book-theme`
- Hosting: Read the Docs (docs.edx.org)
- Translations: Transifex (only 3 projects: edx_students, open_edx_course_authors, open_edx_release_notes)
- CI: GitHub Actions (`.github/workflows/build.yml`) β€” builds on push to `master` and PRs

**Project layout:**

Each of the 13 documentation projects lives under `en_us/<project_name>/` with standard Sphinx structure:
```
en_us/<project>/
β”œβ”€β”€ Makefile
└── source/
β”œβ”€β”€ conf.py
└── index.rst + content .rst files
```

**Shared configuration** in `shared/conf.py` and `shared/edxconf.py` is imported by individual project `conf.py` files.

**Build behavior:** `run_tests.sh` builds all projects in nit-picky Sphinx mode (`-n`) with 4 parallel workers. Warnings and errors are written to log files in `test_root/` via `-w`, then parsed β€” a build with any Sphinx warnings or errors is considered a failure.

**PR requirements:** Run `./run_tests.sh` without warnings or errors before submitting. PRs require SME, product, and partner support sign-off per `.github/PULL_REQUEST_TEMPLATE.md`.
Loading