domd

✓ DoMD - Do Markdown Docs

License: Apache-2.0 Python Version Code Style: Black Tests Docker Support Documentation

DoMD (Do Markdown Docs) is a powerful tool that helps you maintain up-to-date project documentation by automatically detecting, running, and documenting commands from your project files. It generates and updates TODO.md and DONE.md files based on command execution results, making it easier to track what works and what needs attention.

# Start DoMD analyzer
domd

Web Interface

DoMD comes with a modern web interface that allows you to interact with your project’s commands through a user-friendly dashboard.

Starting the Web Interface

# Start the web interface on default port (3000)
domd web

# Specify a custom port
domd web --port 8088

# Start without automatically opening a browser
domd web --no-browser

Web Interface Features

Requirements

Web Interface Setup

  1. Start the web interface:

    domd web --port 8088

  2. Open your browser and navigate to http://localhost:8088

  3. The interface will automatically detect and display your project’s commands

Development Mode

For development, you can run the frontend and backend separately:

# Terminal 1 - Start the backend API
cd backend
python -m domd.api

# Terminal 2 - Start the frontend development server
cd frontend
npm start

✨ Core Features

Demo

Watch the demo

Examples

Explore our comprehensive collection of examples to get started with DoMD:

img.png

Command Testing

DoMD includes powerful command testing capabilities that help you validate and test shell commands in isolated Docker containers:

# Test individual commands
domd test-commands "ls -la" "pwd" "echo Hello"

# Test commands from a file and update .doignore
domd test-commands --update-doignore -f commands.txt

# Skip Docker testing (only validate commands)
domd test-commands --no-docker -f commands.txt

Testing Features

For more details, see the Command Testing Documentation.

Quick Start

Prerequisites

Installation

Choose the installation method that works best for you:

1. **Install DoMD** (if not already installed):

   ```bash
   pip install domd

Or using Docker (no installation required):

   docker run --rm -v $(pwd):/app ghcr.io/wronai/domd domd

Basic Usage

  1. Navigate to your project directory:

    cd /path/to/your/project

  2. Run DoMD:

    # Basic scan
domd

    Or use the web interface:

    domd web

Web Interface Overview

DoMD includes a secure web-based interface for a more interactive experience:

Web Interface Setup

# Start the web interface (default port: 3003)
domd web

# Specify a custom port
domd web --port 8088

# Start without opening browser automatically
domd web --no-browser

# Start with specific host binding
domd web --host 0.0.0.0

DoMD will:

Common Commands

Pro Tip: Run domd regularly to keep your project documentation in sync with your actual project state!

Web Interface

DoMD comes with a web-based interface for a more interactive experience. Here’s how to get it running:

Development Prerequisites

Running the Development Server

  1. Navigate to the frontend directory:

    cd frontend

  2. Install dependencies:

    npm install
# or if you use Yarn:
# yarn

  3. Start the development server:

    npm start
# or if you use Yarn:
# yarn start

  4. Open your browser and visit http://localhost:3003

Building for Production

To create a production build:

cd frontend
npm run build
# or with Yarn:
# yarn build

This will create an optimized production build in the build directory.

Documentation

For detailed documentation, please visit our documentation site or check the docs directory.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to get started.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Need Help?

Open an issue if you need help or have questions.

Pattern Matching

Subdirectory README.md Support

DoMD can automatically scan first-level subdirectories for additional README.md files and execute commands found within them. This is particularly useful for monorepos or projects with multiple components.

Local Development

For local development, you can start both the backend and frontend services:

# Start the backend server
poetry run uvicorn domd.main:app --reload --port 8008

# In a separate terminal, start the frontend
cd frontend
npm install
npm start

Authentication and Login

The web interface is protected by authentication. Use the following default credentials:

Security Note

Change the default password after first login by navigating to User Settings in the web interface.

First-Time Login

  1. Open your web browser and navigate to http://localhost:3000 (development) or http://localhost:3003 (production)
  2. Enter the default credentials:
    • Email/Username: admin
    • Password: admin123
  3. Click “Sign In”
  4. Immediately change your password in the User Settings menu

Web Interface Features

Troubleshooting Login Issues

If you’re having trouble logging in:

  1. Ensure the backend server is running (check terminal for errors)
  2. Verify the frontend is properly connected to the backend (check browser’s developer console for errors)
  3. Clear your browser cache and cookies if experiencing persistent login issues
  4. Check that your credentials are correct (default: admin/admin123)
  5. If you’ve forgotten your password, you can reset it by:
    • Stopping the server
    • Deleting the domd.db file (or your configured database file)
    • Restarting the server (this will recreate the database with default credentials)

Then:

  1. Open http://localhost:3003 in your browser
  2. Log in with the default credentials
  3. Navigate to Settings > Users to change the default password
  4. (Optional) Create additional users with appropriate permissions

Prerequisites

To use the web interface, you’ll need:

Basic Command Line Usage

  1. Navigate to your project directory:

    cd /path/to/your/project

  2. Run DoMD with the web interface:

    # Start the web server
domd web

# The interface will be available at http://localhost:3003 by default

  3. Open your browser and navigate to the displayed URL

Advanced Command Line Usage

For command-line usage, you can run:

domd

DoMD will:

Common Commands

💡 Pro Tip: Run domd regularly to keep your project documentation in sync with your actual project state!

🌐 Web Interface

DoMD comes with a web-based interface for a more interactive experience. Here’s how to get it running:

Development Prerequisites

Running the Development Server

  1. Navigate to the frontend directory:

    cd frontend

  2. Install dependencies:

    npm install
# or if you use Yarn:
# yarn

  3. Start the development server:

    npm start
# or if you use Yarn:
# yarn start

  4. Open your browser and visit http://localhost:3003

Building for Production

To create a production build:

cd frontend
npm run build
# or with Yarn:
# yarn build

This will create an optimized production build in the build directory.

📖 Documentation

For detailed documentation, please visit our documentation site or check the docs directory.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to get started.

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

💡 Need Help?

Open an issue if you need help or have questions.

Pattern Matching

📂 Subdirectory README.md Support

DoMD can automatically scan first-level subdirectories for additional README.md files and execute commands found within them. This is particularly useful for monorepos or projects with multiple components.

How It Works

Example Project Structure

my-project/
├── README.md           # Commands run from project root
├── frontend/
│   └── README.md      # Commands run from frontend/
├── backend/
│   └── README.md      # Commands run from backend/
└── docs/
    └── README.md      # Commands run from docs/

Benefits

🐳 Running Commands in Docker with .dodocker

For better isolation and consistency, you can specify commands that should be executed inside a Docker container using a .dodocker file.

.dodocker File Format

# Commands to run in Docker container
pytest
black --check .
flake8
mypy .

How It Works

Customizing Docker Configuration

You can customize the Docker configuration by creating a Dockerfile in your project root. For example:

FROM python:3.9

# Install additional dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && \
    poetry config virtualenvs.create false && \
    poetry install --no-interaction --no-ansi

DoMD will automatically detect and use this Dockerfile when running commands in a container.

🤖 Programmatic Usage

from domd import ProjectCommandDetector

# Initialize detector
detector = ProjectCommandDetector(
    project_path="./my-project",
    timeout=60,
    exclude_patterns=["*.pyc", "__pycache__/*"]
)

# Scan for commands
commands = detector.scan_project()
print(f"Found {len(commands)} commands")

# Test commands
detector.test_commands(commands)

# Generate report
detector.generate_output_file("RESULTS.md", "markdown")

# Access results
failed_commands = detector.failed_commands
success_rate = (len(commands) - len(failed_commands)) / len(commands) * 100
print(f"Success rate: {success_rate:.1f}%")

🧪 Development

Setup Development Environment

git clone https://github.com/wronai/domd.git
cd domd
poetry install --with dev,docs,testing

# Install pre-commit hooks
poetry run pre-commit install

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=domd --cov-report=html

# Run specific test categories
poetry run pytest -m "unit"
poetry run pytest -m "integration"

Code Quality

# Format code
poetry run black src/ tests/
poetry run isort src/ tests/

# Linting
poetry run flake8 src/ tests/
poetry run mypy src/

# All quality checks
make lint

Building Documentation

# Serve locally
poetry run mkdocs serve

# Build static site
poetry run mkdocs build

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Adding New Parsers

To add support for a new project type, follow these steps:

  1. Create a parser in src/domd/parsers/
  2. Implement the parser interface
  3. Add tests in tests/parsers/
  4. Update documentation

Example parser structure:

from .base import BaseParser

class NewProjectParser(BaseParser):
    def can_parse(self, file_path: Path) -> bool:
        return file_path.name == "config.yaml"

    def parse_commands(self, file_path: Path) -> List[Dict]:
        # Implementation here
        pass

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

📊 Project Stats

🔗 Links

💡 Use Cases

⚡ Quick Examples

CI/CD Integration (GitHub Actions)

name: Project Health Check
on: [push, pull_request]

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'
    - name: Install DoMD
      run: pip install domd
    - name: Run Project Health Check
      run: domd --verbose
    - name: Upload TODO.md if failures
      if: failure()
      uses: actions/upload-artifact@v3
      with:
        name: failed-commands
        path: TODO.md

Make Integration

.PHONY: health-check
health-check:
	@echo "Running project health check..."
	@domd --quiet || (echo "❌ Some commands failed. Check TODO.md" && exit 1)
	@echo "✅ All project commands working!"

.PHONY: health-report
health-report:
	@domd --dry-run --verbose

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: domd-check
        name: Project Command Health Check
        entry: domd
        language: system
        pass_filenames: false
        always_run: true
This site is open source. Improve this page.