Extension for Foliant documentation generator to make docs from multiple sources.
Project description
MultiProject Extension
MultiProject is an extension for Foliant to generate the documentation from multiple sources. MultiProject consists of three parts:
- extension for
foliant.config
package to resolve the!from
YAML tag; - CLI extension for the
src
command; - RepoLink preprocessor.
Installation
$ pip install foliantcontrib.multiproject
Config Extension to Resolve the !from
Tag
This extension resolves the !from
YAML tag in the project config and replaces the value of the tag with chaptres
section of related subproject.
Usage of the Config Extension
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
).
Note that Foliant allows to override default config file name foliant.yml
by using --config
or -c
command line option. To provide correct working of Multiproject extension, the same names of config files should be used in the superproject and in all subprojects.
CLI Extension for the src
Command
This extension supports the command src
to backup the source directory of Foliant project (usually called as src
) and to restore it from prepared backup.
Backing up of the source directory is needed because MultiProject extension modifies this directory by moving the directories of built subprojects into it.
Usage of the CLI Extension
To make a backup of the source directory, use the command:
$ foliant src backup
To restore the source directory from the backup, use the command:
$ foliant src restore
You may use the --config
option to specify custom config file name of your Foliant project. By default, the name foliant.yml
is used:
$ foliant src backup --config alternative_config.yml
Also you may specify the root directory of your Foliant project by using the --project-dir
option. If not specified, current directory will be used.
RepoLink Preprocessor
This preprocessor allows to add into each Markdown source a hyperlink to the related file in Git repository. The hyperlink appears after the first heading of the document.
The preprocessor emulates MkDocs behavior and supports the same options repo_url
and edit_uri
as MkDocs. Applying of the preprocessor to subprojects allows to get links to separate repositories from different pages of a single site (or a single MkDocs project).
Usage of the Preprocessor
To enable the preprocessor, add repolink
to preprocessors
section in the project config:
preprocessors:
- repolink
The preprocessor has a number of options:
preprocessors:
- repolink:
repo_url: https://github.com/foliant-docs/docs/
edit_uri: /blob/master/src/
link_text: ""
link_title: View the source file
link_html_attributes: "class=\"md-icon md-content__icon\" style=\"margin: -7.5rem 0\""
targets:
- pre
repo_url
: URL of the related repository. Default value is an empty string; in this case the preprocessor does not apply. Trailing slashes do not affect.
edit_uri
: Revision-dependent part of URL of each file in the repository. Default value is /blob/master/src/
. Leading and trailing slashes do not affect.
link_text
: Hyperlink text. Default value is Edit this page
.
link_title
: Hyperlink title (the value of title
HTML attribute). Default value is also Edit this page
.
link_html_attributes
: Additional HTML attributes for the hyperlink. By using CSS in combination with class
attribute, and/or style
attribute, you may customize the presentation of your hyperlinks. Default value is an empty string.
targets
: Allowed targets for the preprocessor. If not specified (by default), the preprocessor applies to all targets.
You may override the value of the edit_uri
config option with the FOLIANT_REPOLINK_EDIT_URI
system environment variable. It can be useful in some non-stable testing or staging environments.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for foliantcontrib.multiproject-1.0.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | aa2d5f8a7421527ca6e2686f334e6cee296c42b19d3e68238242fd7800816863 |
|
MD5 | da16b1f0d85d818a60953ca21351b5c4 |
|
BLAKE2b-256 | 0b655dcf15cac30617409ab0e63c51963450fdd61783df1ac390d060c25eae2b |
Hashes for foliantcontrib.multiproject-1.0.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 56a8de24212c93233b28066db7dfb73f83ea0161fabc88eafbbf9d8585e868b9 |
|
MD5 | 115c4f4d9a7d5a7a2495b9f6f51f247c |
|
BLAKE2b-256 | 8bc0b157171ae65658a18508d437bd2779870554fa3f96c9d4ae32a187a7c7d8 |