Skip to content

MultiProject

This extension resolves the !from YAML tag in the project config and replaces the value of the tag with chapters section of related subproject.

Nested subprojects are processed recursively.

Installation

$ pip install foliantcontrib.multiproject

Usage

The subproject location may be specified as a local path, or as a Git repository with optional revision (branch name, commit hash or another reference).

Example of chapters section in the project config:

chapters:
    - index.md
    - !from local_dir
    - !from https://github.com/foliant-docs/docs.git
    - !from https://github.com/some_other_group/some_other_repo.git#develop

Before building the documentation superproject, Multiproject extension calls Foliant to build each subproject into pre target, and then moves the directories of built subprojects into the source directory of the superproject (usually called as src).

Limitations:

  • directory names of subprojects of the same level should be unique;
  • source directories of the multiproject and of all the subprojects should have the same names; also they should be located inside the “root” directories of corresponding projects;
  • config files of the multiproject and of all the subprojects should have the same names;
  • subprojects from remote Git repositories do not need to be newly cloned before each build, but local subprojects are copied into cache before each build;
  • it’s undesirable if the path of the “root” directory of the top-level project contains .multiprojectcache directory as its some part.
Back to top