Publish

Monteur provides Publish CI Job to publish the documentation artifacts to the designated publishers.

The objective of the job is simple: to publish the documentation artifacts to the designated publishers in accordance to their respective instructions..

All users has to do is to issue this command:

1

montuer publish

Job Level Configurations

Montuer does facilitate a job-wide configurations file for configuring Publish CI Job over all settings and supplying job-wide variables.

The configurations, by default, are stored in the data file located in:

1

.configs/monteur/publish/config.toml

The file MUST be strictly named config alongside with the following supported data format's file extension. Currently, Monteur offers the following supported formats, arranged in priority by sequences:

.toml (TOML) - https://github.com/toml-lang/toml

The file structure of the recipe configuration file is detailed from top to bottom in the following sub-sections, in sequences.

Job Level Variables Section

The Monteur's Variables Processing features. All variables defined in this job-wide configuration file only visible to ALL Publish CI Job recipes. It is highly recommended to place all project-based variables data into this list for recipes consistency purposes.

An example of the job-level variables section consists of the following fields:

1
2
3
4
5
6


[Variables]
Version = '1.17.3'
BaseURL = 'https://golang.org/dl/'

[FMTVariables]
Command = 'go{{- .Version -}}'

[Variables] - plain variables list complying to Montuer Plain Variables Definition.
[FMTVariables] - formattable variables list complying to Montuer Formattable Variables Definition.

Recipe Configuration File

All Publish CI Job's recipe configuration files are stored in:

1

.configs/monteur/publish/jobs/

These files can have any filename BUT MUST STRICTLY HAVE any of the the following supported file extensions based on its data format of your choice:

.toml (TOML) - https://github.com/toml-lang/toml

The file structure of the recipe configuration file is detailed from top to bottom in the following sub-sections, in sequences, and in the recommended TOML format.

Recipe's Metadata Section

The recipe's metadata section consists of the following fields:

1
2
3
4
5
6
7


[Metadata]
Name = 'GitHub Pages'
Description = """
Publish web documentations artifact into GitHub Pages.
"""

...

Name - used for recipe identification, reporting, and referencing usage. Monteur recommends keeping it short, concise and without any weird symbols (e.g. space will be replaced by short dash (-)).
Description - mainly for logging and reporting purposes. Describe the details of the recipe.

Recipe's Variables Section

The Monteur's Variables Processing Specification features. All variables defined in this recipe's configuration file are visible ONLY to this recipe. It is highly recommended to abstract as much variables away from your command algorithm as possible so that your user only has to customize these tables and not messing with your algorithm.

The variables section consists of the following fields:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


...

[Variables]
PublishBranch = 'gh-pages'
FirstCommitID = 'Will be overwritten by CMD'

[FMTVariables]
SourceDir = '{{- .DocsDir -}}/public'
DestinationDir = '{{- .WorkingDir -}}/{{- .PublishBranch -}}'

...

[Variables] - plain variables list complying to Montuer Plain Variables Definition.
[FMTVariables] - formattable variables list complying to Montuer Formattable Variables Definition.

Recipe's Dependencies Checking Section

The Monteur's Dependencies Checking features. All 3rd-party dependencies are listed and checked here against the running operating system for ensuring consistent performances and executions of this recipe.

The data structure is compliant to Dependencies Checking Specification. Here is a sample for this recipe:

1
2
3
4
5
6
7
8
9


...

[[Dependencies]]
Name = 'Git'
Condition = 'all-all'
Type = 'command'
Command = 'git'

...

Recipe's Commands Section

The list of executing commands complying to compliant to Commands Execution Unit (CEU) Specification. The commands are executed as instructed in the key recipe sections, usually either execute as per se after all meta processing OR being used to execute horizontally.

The data structure is entirely based on the Commands Execution Unit (CEU) Specification. An example of this recipe's commands section would be:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


...

[[CMD]]
Name = 'Check Artifact Directory Exists and Ready'
Condition = [ 'all-all' ]
Type = 'is-exists'
Source = '{{- .SourceDir -}}/index.html'

[[CMD]]
Name = 'Remove Git Workspace for Publishing Branch'
Condition = [ 'all-all' ]
Type = 'command-quiet'
Source = 'git worktree remove "{{- .DestinationDir -}}"'

[[CMD]]
Name = 'Delete Publishing Directory Regardlessly'
Condition = [ 'all-all' ]
Type = 'delete-recursive-quiet'
Source = '{{- .DestinationDir -}}'

[[CMD]]
Name = 'Create New Publishing Directory'
Condition = [ 'all-all' ]
Type = 'create-path'
Source = '{{- .DestinationDir -}}'

[[CMD]]
Name = 'Add Git Worktree to Publishing Directory'
Condition = [ 'all-all' ]
Type = 'command'
Source = 'git worktree add "{{- .DestinationDir -}}" "{{- .PublishBranch -}}"'

[[CMD]]
Name = 'Get Publish Branch First Commit for Cleaning'
Condition = [ 'all-all' ]
Type = 'command'
Location = '{{- .DestinationDir -}}'
Source = 'git rev-list --max-parents=0 --abbrev-commit HEAD'
Save = 'FirstCommitID'

[[CMD]]
Name = 'Clean Up Publishing Directory for Publish Branch'
Condition = [ 'all-all' ]
Type = 'command'
Location = '{{- .DestinationDir -}}'
Source = 'git reset --hard "{{- .FirstCommitID -}}"'

[[CMD]]
Name = 'Remove All Existing Artifacts'
Condition = [ 'all-all' ]
Type = 'command'
Location = '{{- .DestinationDir -}}'
Source = 'git clean -fd'

[[CMD]]
Name = 'Copy All Publications to Publishing Directory'
Condition = [ 'all-all' ]
Type = 'copy'
Source = '{{- .SourceDir -}}'
Target = '{{- .DestinationDir -}}'

[[CMD]]
Name = 'Git Stage All Artifacts into Publishing Directory'
Condition = [ 'all-all' ]
Type = 'command'
Location = '{{- .DestinationDir -}}'
Source = 'git add .'

[[CMD]]
Name = 'Git Commit All Artifacts into Publishing Directory'
Condition = [ 'all-all' ]
Type = 'command'
Location = '{{- .DestinationDir -}}'
Source = 'git commit -m "Published as of $(git log "--format=format:%H" -1)"'

[[CMD]]
Name = 'Git Push By Force to Publish Branch'
Condition = [ 'all-all' ]
Type = 'command'
Location = '{{- .DestinationDir -}}'
Source = 'git push -f origin "{{- .PublishBranch -}}"'

[[CMD]]
Name = 'Remove Git Workspace for Publishing Branch'
Condition = [ 'all-all' ]
Type = 'command'
Source = 'git worktree remove "{{- .DestinationDir -}}"'

[[CMD]]
Name = 'Delete Publishing Directory Regardlessly'
Condition = [ 'all-all' ]
Type = 'delete-recursive-quiet'
Source = '{{- .DestinationDir -}}'

Currently, this is the last section of the recipe configuration file.

Known Recipes

Instead of working on all the recipes from scratch, Monteur does maintain a number of existing and continuously improved recipes to kick-start your compatible deployment. Here are the available recipes: