Markdown Output for `gira describe`¶

The gira describe command now supports markdown output format for better documentation generation and human readability.

Basic Usage¶

Generate markdown documentation¶

gira describe --format markdown

Generate documentation for a specific command¶

gira describe ticket create --format markdown

Generate documentation for a command group¶

gira describe ticket --format markdown

Options¶

Format Options¶

--format markdown - Output in markdown format instead of JSON
--render - Render the markdown with Rich formatting in the terminal
--full - Generate full documentation with detailed command descriptions
--examples / --no-examples - Include or exclude command examples (default: include)

Examples¶

Basic markdown output¶

gira describe --format markdown

This generates a markdown overview of all Gira commands, organized by: - Core commands (standalone commands) - Command groups (commands with subcommands)

Rendered markdown in terminal¶

gira describe --format markdown --render

Uses Rich to display formatted markdown directly in the terminal with: - Bold headers - Bullet points - Code blocks - Tables

Full documentation¶

gira describe --format markdown --full

Generates comprehensive documentation including: - Table of contents with anchor links - Detailed command sections with usage, arguments, options, and examples - Global options reference

Specific command documentation¶

gira describe ticket create --format markdown

Outputs detailed documentation for a single command including: - Command description - Usage syntax - Arguments with types and descriptions - Options table with types, descriptions, and defaults - Command examples

Command group documentation¶

gira describe epic --format markdown

Shows the command group description and lists all subcommands.

Use Cases¶

Generate CLI reference documentation¶

gira describe --format markdown --full > docs/cli-reference.md

Create command-specific help files¶

for cmd in ticket epic sprint; do
  gira describe $cmd --format markdown > docs/commands/$cmd.md
done

Quick command reference in terminal¶

gira describe ticket create --format markdown --render

Generate documentation without examples¶

gira describe --format markdown --no-examples

Output Structure¶

The markdown output follows a consistent structure:

For the application:¶

# GIRA CLI Reference

[Description]

## Commands

### Core Commands
- `command` - description

### Command Groups
#### group_name
[Group description]
- `subcommand` - description

## Global Options
[Options table]

For individual commands:¶

# `command name`

[Description]

**Usage:**
```bash
gira command [OPTIONS] [ARGUMENTS]

Arguments: - ARG (required) - description

Options: | Option | Type | Description | Default | |--------|------|-------------|---------| | --opt | type | description | default |

Examples:

gira command example

```

Integration with Documentation Tools¶

The markdown output is designed to be compatible with: - GitHub/GitLab documentation - MkDocs and other static site generators - IDE markdown preview - Direct viewing in terminal with --render

Comparison with JSON Output¶

While JSON output is optimized for programmatic use and AI agents: - No formatting by default - Machine-readable structure - Detailed type information

Markdown output is optimized for human readability: - Formatted text with headers and tables - Usage examples - Natural language descriptions - Can be rendered directly in terminal

Markdown Output for gira describe¶