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, this is the latest:

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. This is so the HTML will build the landing page in the root folder.
3. Define a variant specific toc in each index file. Apply exclusion in each toc to each other variant folder.
4. If the content is complex, 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.

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