David Image

Multi-variant documents

One document that shares content with several outputs. You could use this method where you have a single product with customer specific content blocks. Or your product is mostly similar with another product.

I've found a couple of solutions that work with Sphinx:

  1. Define a folder for each variant that includes a conf.py file and an index file.
  2. Add a function to conf.py that copies the customer1/index file to index.rst. The HTML then builds the landing page in the root folder.
  3. Define a variant specific table of contents in each index file. Apply exclusion in each table of contents to each other variant folder.
  4. With complex content, have each variant's topic files in its own docs sub-folder and single-source common content. If not, you can probably just apply logic switches in the topic files via the only directive.
  5. Add a for loop in your pipeline.

For example

# ./customer1/conf.py
conf_original = 'index'
conf_target = '../../index.rst'
shutil.copyfile(conf_original, conf_target)

# ./.gitlab-ci.yml
variables:
  variants: customer1 customer2

html:
  stage: build
  script:
    - for variant in $variants; do
        sphinx-build -c variants/${variant} -b html -t ${variant} . _build/main/${variant};
      done
  artifacts:
    paths:
      - _build/$CI_COMMIT_REF_NAME