CLAUDE

Reference Guide for Claude Code and Developers.

Repository: dingx_sphinx_docs | Local Folder: dingx_sphinx_docs | Technology: Sphinx

📋 Project Overview

This project maintains comprehensive technical and business documentation for dingx using Sphinx, with integrated JIRA task management and multiple output formats.

Key Technologies:

  • Sphinx with sphinx-needs extension

  • JIRA Cloud API integration

  • Python 3.12

  • Multiple output formats: HTML, PDF, DOCX, EPUB, MD

🚀 Quick Start

Building Documentation

# Build HTML (with automatic JIRA sync if credentials set)
make html

# Build without JIRA sync
SKIP_JIRA_SYNC=1 make html

# Build other formats
make latexpdf     # PDF output
make docx         # Word document
make epub         # E-book format
make markdown     # Markdown format

JIRA Synchronization

# Pull tasks from JIRA
make jira-pull

# Push changes to JIRA
make jira-push

# Bidirectional sync
make jira-sync

# Check sync status
make jira-status

📖 Full JIRA Documentation: JIRA Sphinx Sync

📁 Project Structure

.
├── CLAUDE.md                   # This file - main reference for AI/developers
├── Makefile                    # Build commands and automation
├── source/                     # Documentation source files
│   ├── conf.py                 # Main Sphinx configuration
│   ├── index.rst               # Documentation entry point
│   ├── business/               # Business documentation
│   │   ├── business.rst        # Tasks overview
│   │   ├── corporate/          # Company, branding, legal
│   │   ├── finance/            # Investors, funding
│   │   ├── startup/            # Startup programs, support
│   │   └── pitch/              # Pitch deck
│   ├── development/            # Development documentation
│   ├── coremodel/              # Core infrastructure
│   ├── design/                 # Brand and design
│   └── _static/                # Static assets (logos, images)
├── tools/                      # Utilities and sync scripts
│   ├── JIRA_SPHINX_SYNC.md     # JIRA synchronization guide
│   ├── vm_deployment_guide.md  # VM deployment and management guide
│   ├── deploy_vm.sh            # VM deployment script
│   ├── setup_jira_env.sh       # JIRA environment setup script
│   ├── jira_sphinx_sync.py     # Main JIRA sync script
│   ├── jira2needs.py           # JIRA to sphinx-needs converter
│   ├── jade.yml                # JIRA configuration
│   ├── sync_state.json         # Sync state tracking (auto-generated)
│   └── convert_todos.py        # Todo to task converter
└── build/                      # Generated documentation (gitignored)

⚙️ Configuration Files

Note: For guidance on INI vs YAML configuration formats, see the Configuration File Format Best Practices guide.

conf.py

Main Sphinx configuration with:

  • JIRA integration settings

  • sphinx-needs task configuration

  • Theme settings (Furo)

  • Build customizations

  • Auto-sync hooks

jade.yml

JIRA synchronization configuration:

  • JIRA Cloud URL and authentication

  • JQL queries for task filtering

  • Field mappings (JIRA ↔ Sphinx)

  • Status transformations

Makefile

Build automation with targets for:

  • HTML, PDF, DOCX, EPUB, MD builds

  • JIRA sync operations

  • Clean operations

  • Environment setup

🎯 Key Features

1. JIRA Integration

Bidirectional synchronization between JIRA and Sphinx-Needs:

  • Pull tasks from JIRA into documentation

  • Push Sphinx changes back to JIRA

  • Automatic sync during builds

  • Conflict-aware synchronization

📖 Details: JIRA Sphinx Sync

2. Task Management

Sphinx-Needs for requirements tracking:

  • Task directives with metadata

  • Status tracking: to-do, in-progress, done, parking

  • Assignees, priorities, due dates

  • Automatic task IDs based on file position

3. Multiple Output Formats

Single source, multiple outputs:

  • HTML (Furo theme) - Primary output

  • PDF - Professional documentation

  • DOCX - Editable Word documents

  • EPUB - E-book format

  • MD - For GitHub/wikis

4. Automated Builds

  • Pre-build JIRA sync hooks

  • Auto-generation of documentation

  • Theme customizations per format

  • Warning suppression and filtering

📝 Common Workflows

Adding/Updating Tasks

  1. Edit RST files:

    .. task:: Implement feature X
   :status: to-do
   :assignee: info@dingx.co
   :priority: High
   :duedate: 2025-12-31

   Task description here.

  2. Sync with JIRA:

    make jira-sync

  3. Build documentation:

    make html

Updating Status Transformations

When JIRA status names change or new statuses are added:

  1. Update jade.yml:

    transforms:
  status:
    "To Do": to-do
    "In Progress": in-progress
    "Done": done

  2. Update conf.py:

    needs_statuses = [
    {"name": "to-do", "description": "...", "color": "#d3d3d3"},
    ...
]

  3. Update sync scripts if needed:

Working with Auto-Generated Task IDs

Tasks automatically get IDs based on their position in files:

  • source/business/finance/finance.rst → TD_FINA_001, TD_FINA_002, …

  • source/business/startup/startup.rst → TD_STAR_001, TD_STAR_002, …

  • source/business/corporate/corporate.rst → TD_CORP_001, TD_CORP_002, …

Note: Don’t manually assign IDs to non-JIRA tasks - they’re auto-generated!

🔧 Important Conventions for Claude Code

Status Values

Always use these exact status values in Sphinx:

  • to-do - Not started / planned

  • in-progress - Actively being worked on

  • done - Completed

  • parking - On hold / blocked

JIRA Mapping:

  • JIRA “To Do” → Sphinx to-do

  • JIRA “In Progress” → Sphinx in-progress

  • JIRA “Done” → Sphinx done

  • JIRA “PARKING” → Sphinx parking

User Mapping

  • Sphinx assignee: info@dingx.co (email format)

  • JIRA assignee: Friedrich Moehring (display name)

  • JIRA Account ID: 5f8eeffd14dd46006805afc4

Configured in dingx_sphinx_docs.tools.jira_sphinx_sync

  • _resolve_jira_user() - Sphinx → JIRA

  • _resolve_sphinx_assignee() - JIRA → Sphinx

Task Directive Format

.. task:: Task title here
   :status: to-do
   :assignee: info@dingx.co
   :priority: Medium
   :duedate: YYYY-MM-DD
   :tags: tag1, tag2

   Task description content with proper indentation.

   Multiple paragraphs are fine.

Important:

  • Task directives must NOT be indented (start at column 0)

  • Options are indented with tabs (in RST files)

  • Content is indented with tabs

  • JIRA tasks have IDs like JIRA_BUS-123

  • Auto-generated tasks have IDs like TD_FINA_001

File Editing Guidelines

When updating RST files with task statuses:

  • Use replace_all=true for batch status updates

  • Preserve tab indentation in RST files (not spaces)

  • Don’t modify JIRA-generated task sections manually

  • Check filters in needtable directives match status names

🔐 Environment Setup

JIRA Credentials

# Set up credentials (never commit these!)
export JIRA_USER="info@dingx.co"
export JIRA_API_TOKEN="your_api_token_here"

# Or use the setup script
./tools/setup_jira_env.sh

Get API Token: https://id.atlassian.com/manage-profile/security/api-tokens

Python Virtual Environment

# The project uses these virtual environments:
# - django_landing_simple
# - django_webapps_fullstack
# - odoo_xmlrpc_twisted
# - odoo_xmlrpc_twisted
# - ...

# Configured in `source/conf.py` sys.path

🏗️ Architecture Decisions

Why JIRA Sync?

  • Single source of truth for tasks

  • Business team uses JIRA, docs team uses RST

  • Automated synchronization prevents drift

  • Maintains task history and audit trail

Why Sphinx-Needs?

  • Requirements traceability

  • Task relationships and dependencies

  • Professional rendering in multiple formats

  • Integration with Sphinx ecosystem

Why Multiple Output Formats?

  • HTML: Interactive browsing, search, navigation

  • PDF: Professional documentation, printing, archival

  • DOCX: Editing, collaboration, corporate templates

  • EPUB: Mobile reading, offline access

Why Furo Theme?

  • Clean, modern design

  • Excellent mobile support

  • Fast and lightweight

  • Customizable appearance

🐛 Troubleshooting

JIRA Sync Issues

# Check credentials
make jira-status

# Verify JIRA connection
curl -u "$JIRA_USER:$JIRA_API_TOKEN" \
     https://dingx.atlassian.net/rest/api/3/myself

# Check sync state
cat tools/sync_state.json

# Manual sync with verbose output
python tools/jira_sphinx_sync.py pull

Build Issues

# Clean build directory
make clean

# Rebuild from scratch
make clean html

# Check for missing dependencies
pip install -r requirements.txt

# Check Python paths in conf.py
grep sys.path source/conf.py

Task Detection Issues

  • Ensure task directives start at column 0 (no indentation)

  • Check that task options use consistent indentation (tabs)

  • Verify status values match configured needs_statuses

  • Confirm JIRA task IDs follow pattern: JIRA_PROJECT-###

📚 Additional Documentation

  • JIRA Sync: JIRA Sphinx Sync

  • Sphinx-Needs: https://sphinx-needs.readthedocs.io/

  • Furo Theme: https://pradyunsg.me/furo/

  • reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/

📞 Support & Maintenance

When Things Break

  1. Check this file (CLAUDE) first

  2. Review relevant documentation in tools/

  3. Check Sphinx build warnings/errors

  4. Verify environment variables

  5. Test JIRA connectivity

Regular Maintenance

  • Update JIRA API token annually

  • Review and update status mappings as needed

  • Clean build directory periodically

  • Keep dependencies updated

🎓 Learning Resources

For Claude Code

This file is your primary reference. Key things to remember:

  • Always use “to-do” not “open” for status

  • Respect tab indentation in RST files

  • JIRA sync happens automatically during HTML builds

  • User mapping: info@dingx.co ↔ Friedrich Moehring

  • Don’t manually create IDs for non-JIRA tasks

For Developers

Last updated: 2025-11-08