Skip to content

Documentation Setup Guide

This guide will help you set up the local development environment for building and testing the DataDialogue documentation.

Prerequisites

  • Python 3.8 or higher
  • pip (Python package installer)
  • Git

Installation

  1. Clone the repository: 

    git clone https://github.com/ggeop/DataDialogueLLM.git
cd DataDialogueLLM

  2. Create a virtual environment (recommended): 

    # On Windows
python -m venv venv
.\venv\Scripts\activate

# On Unix or MacOS
python3 -m venv venv
source venv/bin/activate

  3. Install documentation dependencies: 

    pip install -r docs/documentation/requirements.py

Building Documentation

  1. Navigate to the project root: 

    cd DataDialogueLLM

  2. Build the documentation: 

    mkdocs build

  3. Serve the documentation locally: 

    mkdocs serve

  4. Access the documentation at http://127.0.0.1:8000

Testing Documentation

  1. Live Preview
  2. Run mkdocs serve
  3. Open http://127.0.0.1:8000 in your browser

  4. Changes will automatically reload

  5. Build Testing

  6. Run mkdocs build
  7. Check the site directory for the built documentation

  8. Verify all pages render correctly

  9. Link Checking

  10. Install link checking tool: 
    pip install linkchecker
  11. Run link checker: 
    linkchecker http://127.0.0.1:8000

Common Issues

  1. Missing Dependencies

  2. Solution: Run pip install -r docs/documentation/requirements.py

  3. Build Errors

  4. Check for syntax errors in markdown files
  5. Verify all referenced files exist

  6. Check mkdocs.yml configuration

  7. Theme Issues

  8. Clear browser cache
  9. Restart mkdocs serve
  10. Verify theme configuration in mkdocs.yml

Best Practices

  1. Writing Documentation
  2. Use clear, concise language
  3. Follow the established structure
  4. Include code examples where relevant

  5. Add screenshots for UI-related content

  6. Version Control

  7. Create a new branch for documentation changes
  8. Use descriptive commit messages

  9. Test changes locally before pushing

  10. Maintenance

  11. Keep dependencies up to date
  12. Regularly check for broken links
  13. Update screenshots when UI changes

Additional Resources