Our V3 documentation build system needs the capability to build multiple documentation content sets from multiple source repositories. While we aim to consolidate from our current list of 75+ repositories, Elastic's documentation source files will continue to be distributed across multiple repos. V3 should be flexible enough to accommodate this multi-repository structure without compromising build efficiency.
Existing Solutions
There are precedents for handling multi-repo documentation builds within Elastic’s existing build systems, though each system takes a different approach:
AsciiDoc Build System: The AsciiDoc system sources files at build time by cloning any relevant repositories for each build. One thing to note is that this approach can be quite slow, especially when cloning repositories like Kibana, which are quite large.
Docsmobile Build System: Docsmobile uses a centralized "wordlake" where content is moved once it’s merged into the relevant source repository. Production builds then only need to clone this single repository, streamlining the build process by centralizing all required content.
Requirements
Flexible Content Sourcing: Support for multiple source repos (regardless of whether that means at build time or at merge time).
Content Set Configuration: V3 must support defining multiple documentation content sets within a centralized configuration file (e.g., site.yaml), where each set can specify things like its source repository, paths, dependencies, and other settings.
Global Navigation and Version Management: V3 should provide a mechanism to generate a global navigation structure that can include content sets from multiple repositories.
Summary
Our V3 documentation build system needs the capability to build multiple documentation content sets from multiple source repositories. While we aim to consolidate from our current list of 75+ repositories, Elastic's documentation source files will continue to be distributed across multiple repos. V3 should be flexible enough to accommodate this multi-repository structure without compromising build efficiency.
Existing Solutions
There are precedents for handling multi-repo documentation builds within Elastic’s existing build systems, though each system takes a different approach:
AsciiDoc Build System: The AsciiDoc system sources files at build time by cloning any relevant repositories for each build. One thing to note is that this approach can be quite slow, especially when cloning repositories like Kibana, which are quite large.
Docsmobile Build System: Docsmobile uses a centralized "wordlake" where content is moved once it’s merged into the relevant source repository. Production builds then only need to clone this single repository, streamlining the build process by centralizing all required content.
Requirements
site.yaml), where each set can specify things like its source repository, paths, dependencies, and other settings.