1

I feel like this may have been asked before but I can't quite fit together existing questions into this exact problem.

I have a Git repository where I am storing Sphinx files and builds for a single doc. I want to reuse some of the files from that doc (css, logos, etc) for other docs and ideally keep track of the changes to these 'core files' separately from the rest of the docs (e.g., the rst).

I think one way to do this would be to split the 'core' files into a separate Git repository, but I am struggling to find a non-manual way of adding these core files to the repository.

The file structure I currently have is akin to

| Doc repository
 |-- Sphinx
  |- Built docs folder
  |- Reusable components in folders
  | Some files
  | A reusable file

And ideally I want to be able to separate (and then add again) the reusable items.

I tried submodules, but I learned they cannot be used to add files to an existing folder, and so that won't work as I need that reusable file in the same folder.

I've been looking into subtrees but I am having trouble understanding whether they accomplish what I want.

Ideally, the resulting structure would be something akin to

| Doc repository
 |-- Sphinx
  |- Built docs folder
  | Some files
  | + Some command to add reusable stuff in this same directory

| Reusable repository
 |- Reusable folders
 | Reusable file
KDM
  • 81
  • 7

1 Answers1

1

I know how to reuse a submodule content coming from the same repo (but different branch), but that always implies having said reused files in a separate folder.

Still, you could:

  • declare that submodule in order to get your reusable files
  • add and version symbolic links, one for each reusable files, in the right folder (meaning with your other existing tracked files).
    Each symlink would reference its corresponding file in the submodule folder.

That is a workaround which would not scale well (if you add or remove files in the submodule repo, you would need to mirror that in the symlinks), but that would achieve what you are after.

Ideally though, those reusable files would be addressed by a relative URL, which would include a subfolder name, which would make the use of symlinks unnecessary.

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • The symbolic links idea is one I hadn't thought of! As far as I can tell, there is only one reusable file which needs to be in the same folder as existing content - so that would be managable. You're right in that the content in the folders should be accessible via an appropriate relative URL. – KDM Apr 08 '19 at 15:35
  • I wanted to check and make sure this would actually work before marking it. It was a mistake for me to try moving the reusable stuff up a level - that required weirdness in my conf.py. Bundling them deeper into the Doc repository was way easier. – KDM Apr 09 '19 at 21:17