Using GitLab as a Component Authoring system

Challenge

• Minimize the amount of duplicated content between documents/outputs.
• Share content enterprise-wide.
• Only store critical content in one place across the entire organization (a golden source).

Result

A custom Sphinx directive that allows authors to source figures, tables, or text from any GitLab repository into a target document.

.. csv-from-gitlab:: Example CSV table
  :project_path: path/to/gitlab/repository
  :git_ref: [commit|branch]
  :file_path: path/to/source/file
  :dest_dir: docs/tables
  :header-rows: 1

Background

Although GitLab acts as a single Document Management System, documents themselves were always siloed as repositories. As in, we could share content within a document to itself, but we could not intuitively share content from another source document into a target document. This is a limitation of Sphinx.

For example, we have a single product with several variants. We manage all the variant documentation within a single repository. This allows us to output (for example) 10 datasheets with minor differences and share content within themselves. This means that our core data for this particular product is only stored in one place.

However, if that core data originates from an Engineering repository, we need to copy that data into our datasheet repository. This creates an unwanted situation where we have critically managed content in two places.

By creating a custom Sphinx directive, we can define any component across our organization's GitLab and pull it into our target document. These directives add functionality to the existing Docutils scripts included in Sphinx.