Where to keep assets for documentation generation as to not clutter the main repository

Question

I have a large C++ project I'm hoping to release publicly soon (it is currently an internal development at work).

We have a large auto documentation setup which uses doxygen and sphinx, however our documentation includes many images (useful as our tool deals primarily with image processing, geometries, and rendering).

Currently I'm just keeping the images sitting in a shared folder, and reference them when I build a copy of the docs. But when we publicly release the project I'd like to somehow provide them such that anyone could easily build the documentation by simply setting the BUILD_DOCS cmake option to ON, and not have to worry about sourcing files from all over the place. But at the same time, I don't want to include them in the repository itself as I doubt most people would be building the docs from scratch and so would never need the images at all.

One solution I was thinking of was to keep the images in a separate repository that the main repo simply contains as a submodule. Then I can configure the CMake to simply go fetch the contents of that submodule if someone is building the docs. I do something similar already with vcpkg which I have included as a submodule to simplify the build process (but still allow people to bypass using it)

Is that a sensible option? Or is there a better way of dealing with this? The advice I've gotten most often is to just not care about it but I really like how small my repository size is and adding these images would immediately grow the repo an order of magnitude in size.

Answer 1

I don't want to include them in the repository itself as I doubt most people would be building the docs from scratch

The main criterion of what belongs in the same repository is not whether someone will make direct use of everything. Opinions on a monorepo aside, it's a valid example of how not everyone will touch everything that's in such a monorepo.

The main criterion is whether it's important that the included items share a versioning lifecycle. Do you want to ensure that a specific version of the docs (and generation tools) refers to a specific version of your code? If this is paramount, then there is sufficient justification for adding it to the same versioned repository.

If, however, the document generation version is separate from the codebase version, then there's no point in adding them to the same repository.

One solution I was thinking of was to keep the images in a separate repository that the main repo simply contains as a submodule.

The question then becomes how you know which version of repo A should be referenced by repo B? Let's say you have 20 repo A versions (= codebase), and 3 repo B versions (= images, or all of the document generation tooling). Which version of repo A references which version of repo B?

I really like how small my repository size is and adding these images would immediately grow the repo an order of magnitude in size

Differential commits mean that you don't really suffer from having the images in your repo, other than the initial checkout.

If the images change frequently, then that's the cost of doing business. The assumption here being that you'd only add it to the repo if keeping the version between code and documentation synchronized is more important to you than some bandwidth usage.