Skip to content

GitLab Setup for Bluefly Documentation

This guide explains how to set up the Bluefly documentation system in GitLab, including the central documentation repository (BFDOCS) and the integration with individual project repositories.

Prerequisites

Before setting up the documentation system, ensure you have:

  1. Administrator access to the GitLab organization
  2. Access to all Bluefly project repositories
  3. Basic understanding of GitLab CI/CD
  4. Python 3.7+ installed locally
  5. Node.js 18+ installed locally

Repository Setup

Creating the BFDOCS Repository

  1. Log in to GitLab and navigate to your organization
  2. Click "New project" → "Create blank project"
  3. Enter the following information:
  4. Project name: bfdocs
  5. Visibility level: Internal
  6. Initialize repository with a README
  7. Click "Create project"

Initial Configuration

Clone the repository locally and set up the basic structure:

git clone https://gitlab.com/bluefly/bfdocs.git
cd bfdocs

# Create standard directories
mkdir -p docs/architecture docs/guides docs/integration docs/ml docs/api docs/setup docs/projects
mkdir -p assets/images assets/stylesheets
mkdir -p scripts templates

Adding MkDocs Configuration

  1. Copy the mkdocs.yml file from this repository to your local clone
  2. Install MkDocs locally to test the configuration: 
    pip install mkdocs mkdocs-material
mkdocs serve
  3. Visit http://localhost:8000 to verify the site is working

Setting Up GitLab Pages

  1. Copy the .gitlab-ci.yml file from this repository to your local clone
  2. Commit and push the changes: 
    git add .
git commit -m "Initial documentation setup"
git push
  3. Navigate to your GitLab project → Settings → Pages to verify the site is deployed

CI/CD Configuration

Setting Up CI/CD Variables

  1. Navigate to your GitLab project → Settings → CI/CD → Variables
  2. Add the following variables:
  3. MKDOCS_MATERIAL_VERSION: 9.4.6
  4. PYTHON_VERSION: 3.10

Creating Access Tokens

To allow project repositories to update the central documentation, create an access token:

  1. Navigate to your GitLab project → Settings → Access Tokens
  2. Create a new token with the following settings:
  3. Token name: docs-sync-token
  4. Expiration date: Set an appropriate expiration (e.g., 1 year)
  5. Scopes: api, read_repository, write_repository
  6. Copy the generated token for later use

Integrating with Project Repositories

Adding Documentation CI/CD to Projects

For each project that should participate in the documentation system:

  1. Navigate to the project repository
  2. Create a .gitlab-ci.yml file if it doesn't exist
  3. Add the following include statement at the top: 
    include:
  - project: 'bluefly/bfdocs'
    file: 'ci/documentation.yml'
  4. Add the documentation token as a CI/CD variable:
  5. Navigate to the project's Settings → CI/CD → Variables
  6. Add a variable named DOCS_TRIGGER_TOKEN with the value of the token created earlier
  7. Set it to "Protected" and not "Masked"

Initial Documentation Sync

To perform an initial sync of project documentation:

  1. Clone the project repository
  2. Run the sync script manually: 
    python /path/to/BFDOCS/scripts/sync_project_docs.py --project $(basename $(pwd)) --direction to_central --bfdocs /path/to/BFDOCS
  3. Commit and push the changes to BFDOCS

Verification

Once the setup is complete, verify that the documentation system is working:

  1. Make a change to a project's documentation
  2. Commit and push with a message containing "docs:"
  3. Check that the CI/CD pipeline runs successfully
  4. Verify that the change appears in the central documentation site

Configuring GitLab Webhooks (Optional)

For more immediate updates, set up webhooks:

  1. Navigate to the project repository → Settings → Webhooks
  2. Add a new webhook with:
  3. URL: https://gitlab.com/api/v4/projects/<BFDOCS-PROJECT-ID>/trigger/pipeline
  4. Secret token: The docs-sync-token created earlier
  5. Trigger: Push events, Comments, Merge requests
  6. Branch filter: main
  7. Click "Add webhook"

Customizing the Documentation Site

Updating Theme Colors

  1. Edit the mkdocs.yml file and modify the theme section: 

    theme:
  name: material
  palette:
    primary: indigo  # Change to your brand color
    accent: indigo

  2. Edit the assets/stylesheets/extra.css file to add custom styles

  3. Commit and push the changes

Adding Custom Logo and Favicon

  1. Place your logo in assets/images/
  2. Update the mkdocs.yml file: 
    theme:
  name: material
  logo: assets/images/your-logo.png
  favicon: assets/images/favicon.ico
  3. Commit and push the changes

Advanced Configuration

Multiple Documentation Versions

To support multiple versions of documentation:

  1. Install the mike plugin: 

    pip install mike

  2. Add mike configuration to mkdocs.yml: 

    extra:
  version:
    provider: mike

  3. Update the CI/CD pipeline to deploy versioned documentation with mike

Automated Testing

To add automated testing of documentation:

  1. Add link checking to the CI/CD pipeline: 

    test-links:
  stage: test
  script:
    - pip install mkdocs-linkcheck
    - mkdocs linkcheck

  2. Add spelling checking: 

    test-spelling:
  stage: test
  script:
    - pip install pyspelling
    - pyspelling -c .spellcheck.yml

Troubleshooting

Common Issues

Documentation Not Syncing

  1. Check the CI/CD pipeline logs for errors
  2. Verify that the documentation token is correctly set up
  3. Ensure the include statement in the project's .gitlab-ci.yml is correct
  4. Check that the commit message contains the required trigger keyword

GitLab Pages Not Updating

  1. Check the Pages settings in the GitLab project
  2. Verify that the pages job in the CI/CD pipeline completed successfully
  3. Clear your browser cache or try a different browser

Build Errors

  1. Check for syntax errors in the MkDocs configuration
  2. Verify that all required plugins are installed
  3. Check for broken links or references in the documentation

Maintenance

Regular Tasks

  1. Rotate the documentation access token annually
  2. Review and update the documentation structure as needed
  3. Clean up obsolete documentation
  4. Update dependencies (MkDocs, theme, plugins)

Monitoring

Set up monitoring for the documentation site:

  1. Add uptime monitoring to check the GitLab Pages site
  2. Set up alerts for documentation build failures
  3. Regularly check for broken links and outdated content

Conclusion

You now have a fully configured documentation system that aggregates documentation from all your Bluefly projects into a central, easily navigable site. This system automatically keeps documentation in sync and publishes changes when they occur.

For help or further customization, contact the Bluefly documentation team or open an issue in the BFDOCS repository.