schedule: updated documentation

creativeprojects · Mar 10, 2024 · 35f7b6a · 35f7b6a
1 parent f7755a3
commit 35f7b6a
Show file tree

Hide file tree

Showing 6 changed files with 30 additions and 25 deletions.
diff --git a/config/info.go b/config/info.go
@@ -610,7 +610,7 @@ func init() {
 func NewGlobalInfo() NamedPropertySet {
 	set := &namedPropertySet{
 		name:        constants.SectionConfigurationGlobal,
-		description: "global settings",
+		description: "Global settings",
 		propertySet: propertySetFromType(infoTypes.global),
 	}
 	customizeProperties(constants.SectionConfigurationGlobal, set.properties)
@@ -621,7 +621,7 @@ func NewGlobalInfo() NamedPropertySet {
 func NewGroupInfo() NamedPropertySet {
 	set := &namedPropertySet{
 		name:        constants.SectionConfigurationGroups,
-		description: "profile groups",
+		description: "Profile groups",
 		propertySet: propertySetFromType(infoTypes.group),
 	}
 	customizeProperties(constants.SectionConfigurationGroups, set.properties)
@@ -632,7 +632,7 @@ func NewGroupInfo() NamedPropertySet {
 func NewMixinsInfo() NamedPropertySet {
 	return &namedPropertySet{
 		name:        constants.SectionConfigurationMixins,
-		description: "global mixins declaration",
+		description: "Global mixins declaration.",
 		propertySet: propertySetFromType(infoTypes.mixins),
 	}
 }
@@ -641,7 +641,7 @@ func NewMixinsInfo() NamedPropertySet {
 func NewMixinUseInfo() NamedPropertySet {
 	return &namedPropertySet{
 		name:        constants.SectionConfigurationMixinUse,
-		description: "named mixin reference to apply to the current location",
+		description: "Named mixin reference to apply to the current location.",
 		propertySet: propertySetFromType(infoTypes.mixinUse),
 	}
 }
@@ -650,7 +650,7 @@ func NewMixinUseInfo() NamedPropertySet {
 func NewScheduleConfigInfo() NamedPropertySet {
 	return &namedPropertySet{
 		name:        constants.SectionConfigurationSchedule,
-		description: "schedule configuration structure",
+		description: "Schedule configuration structure. Can be used to define schedules in profiles and groups.",
 		propertySet: propertySetFromType(infoTypes.scheduleConfig),
 	}
 }

diff --git a/config/profile.go b/config/profile.go
@@ -291,16 +291,16 @@ func (s *SectionWithScheduleAndMonitoring) IsEmpty() bool { return s == nil }
 // ScheduleBaseSection contains the parameters for scheduling a command (backup, check, forget, etc.)
 type ScheduleBaseSection struct {
 	scheduleConfig                  *ScheduleConfig
-	Schedule                        any            `mapstructure:"schedule" show:"noshow" examples:"hourly;daily;weekly;monthly;10:00,14:00,18:00,22:00;Wed,Fri 17:48;*-*-15 02:45;Mon..Fri 00:30" description:"Configures the schedule can be times in systemd timer format or a config structure"`
+	Schedule                        any            `mapstructure:"schedule" show:"noshow" examples:"hourly;daily;weekly;monthly;10:00,14:00,18:00,22:00;Wed,Fri 17:48;*-*-15 02:45;Mon..Fri 00:30" description:"Configures the scheduled execution of this profile section. Can be times in systemd timer format or a config structure"`
 	SchedulePermission              string         `mapstructure:"schedule-permission" show:"noshow" default:"auto" enum:"auto;system;user;user_logged_on" description:"Specify whether the schedule runs with system or user privileges - see https://creativeprojects.github.io/resticprofile/schedules/configuration/"`
 	ScheduleLog                     string         `mapstructure:"schedule-log" show:"noshow" examples:"/resticprofile.log;tcp://localhost:514" description:"Redirect the output into a log file or to syslog when running on schedule"`
 	SchedulePriority                string         `mapstructure:"schedule-priority" show:"noshow" default:"background" enum:"background;standard" description:"Set the priority at which the schedule is run"`
 	ScheduleLockMode                string         `mapstructure:"schedule-lock-mode" show:"noshow" default:"default" enum:"default;fail;ignore" description:"Specify how locks are used when running on schedule - see https://creativeprojects.github.io/resticprofile/schedules/configuration/"`
 	ScheduleLockWait                maybe.Duration `mapstructure:"schedule-lock-wait" show:"noshow" examples:"150s;15m;30m;45m;1h;2h30m" description:"Set the maximum time to wait for acquiring locks when running on schedule"`
 	ScheduleEnvCapture              []string       `mapstructure:"schedule-capture-environment" show:"noshow" default:"RESTIC_*" description:"Set names (or glob expressions) of environment variables to capture during schedule creation. The captured environment is applied prior to \"profile.env\" when running the schedule. Whether capturing is supported depends on the type of scheduler being used (supported in \"systemd\" and \"launchd\")"`
-	ScheduleIgnoreOnBattery         maybe.Bool     `mapstructure:"schedule-ignore-on-battery" show:"noshow" default:"false" description:"Don't schedule the start of this profile when running on battery"`
-	ScheduleIgnoreOnBatteryLessThan int            `mapstructure:"schedule-ignore-on-battery-less-than" show:"noshow" default:"" description:"Don't schedule the start of this profile when running on battery, and the battery charge left is less than the value"`
-	ScheduleAfterNetworkOnline      maybe.Bool     `mapstructure:"schedule-after-network-online" show:"noshow" description:"Don't schedule the start of this profile when the network is offline (supported in \"systemd\")."`
+	ScheduleIgnoreOnBattery         maybe.Bool     `mapstructure:"schedule-ignore-on-battery" show:"noshow" default:"false" description:"Don't start this schedule when running on battery"`
+	ScheduleIgnoreOnBatteryLessThan int            `mapstructure:"schedule-ignore-on-battery-less-than" show:"noshow" default:"" examples:"20,33,50,75" description:"Don't start this schedule when running on battery and the state of charge is less than this percentage"`
+	ScheduleAfterNetworkOnline      maybe.Bool     `mapstructure:"schedule-after-network-online" show:"noshow" description:"Don't start this schedule when the network is offline (supported in \"systemd\")"`
 }
 
 func (s *ScheduleBaseSection) setRootPath(_ *Profile, _ string) {

diff --git a/config/schedule.go b/config/schedule.go
@@ -34,15 +34,15 @@ const (
 
 // ScheduleBaseConfig is the base user configuration that could be shared across all schedules.
 type ScheduleBaseConfig struct {
-	Permission              string         `mapstructure:"permission" show:"noshow" default:"auto" enum:"auto;system;user;user_logged_on" description:"Specify whether the schedule runs with system or user privileges - see https://creativeprojects.github.io/resticprofile/schedules/configuration/"`
-	Log                     string         `mapstructure:"log" show:"noshow" examples:"/resticprofile.log;tcp://localhost:514" description:"Redirect the output into a log file or to syslog when running on schedule"`
-	Priority                string         `mapstructure:"priority" show:"noshow" default:"background" enum:"background;standard" description:"Set the priority at which the schedule is run"`
-	LockMode                string         `mapstructure:"lock-mode" show:"noshow" default:"default" enum:"default;fail;ignore" description:"Specify how locks are used when running on schedule - see https://creativeprojects.github.io/resticprofile/schedules/configuration/"`
-	LockWait                maybe.Duration `mapstructure:"lock-wait" show:"noshow" examples:"150s;15m;30m;45m;1h;2h30m" description:"Set the maximum time to wait for acquiring locks when running on schedule"`
-	EnvCapture              []string       `mapstructure:"capture-environment" show:"noshow" default:"RESTIC_*" description:"Set names (or glob expressions) of environment variables to capture during schedule creation. The captured environment is applied prior to \"profile.env\" when running the schedule. Whether capturing is supported depends on the type of scheduler being used (supported in \"systemd\" and \"launchd\")"`
-	IgnoreOnBattery         maybe.Bool     `mapstructure:"ignore-on-battery" show:"noshow" default:"false" description:"Don't schedule the start of this profile when running on battery"`
-	IgnoreOnBatteryLessThan int            `mapstructure:"ignore-on-battery-less-than" show:"noshow" default:"" description:"Don't schedule the start of this profile when running on battery, and the battery charge left is less than the value"`
-	AfterNetworkOnline      maybe.Bool     `mapstructure:"after-network-online" show:"noshow" description:"Don't schedule the start of this profile when the network is offline (supported in \"systemd\")."`
+	Permission              string         `mapstructure:"permission" default:"auto" enum:"auto;system;user;user_logged_on" description:"Specify whether the schedule runs with system or user privileges - see https://creativeprojects.github.io/resticprofile/schedules/configuration/"`
+	Log                     string         `mapstructure:"log" examples:"/resticprofile.log;tcp://localhost:514" description:"Redirect the output into a log file or to syslog when running on schedule"`
+	Priority                string         `mapstructure:"priority" default:"background" enum:"background;standard" description:"Set the priority at which the schedule is run"`
+	LockMode                string         `mapstructure:"lock-mode" default:"default" enum:"default;fail;ignore" description:"Specify how locks are used when running on schedule - see https://creativeprojects.github.io/resticprofile/schedules/configuration/"`
+	LockWait                maybe.Duration `mapstructure:"lock-wait" examples:"150s;15m;30m;45m;1h;2h30m" description:"Set the maximum time to wait for acquiring locks when running on schedule"`
+	EnvCapture              []string       `mapstructure:"capture-environment" default:"RESTIC_*" description:"Set names (or glob expressions) of environment variables to capture during schedule creation. The captured environment is applied prior to \"profile.env\" when running the schedule. Whether capturing is supported depends on the type of scheduler being used (supported in \"systemd\" and \"launchd\")"`
+	IgnoreOnBattery         maybe.Bool     `mapstructure:"ignore-on-battery" default:"false" description:"Don't start this schedule when running on battery"`
+	IgnoreOnBatteryLessThan int            `mapstructure:"ignore-on-battery-less-than" default:"" examples:"20,33,50,75" description:"Don't start this schedule when running on battery and the state of charge is less than this percentage"`
+	AfterNetworkOnline      maybe.Bool     `mapstructure:"after-network-online" description:"Don't start this schedule when the network is offline (supported in \"systemd\")"`
 }
 
 // scheduleBaseConfigDefaults declares built-in scheduling defaults

diff --git a/config/template.go b/config/template.go
@@ -78,10 +78,12 @@ func (t *TemplateInfoData) collectPropertiesByType(set PropertySet, byType map[s
 	}
 }
 
-// NestedProfileSections lists SectionInfo of all nested sections that may be used inside the configuration
-func (t *TemplateInfoData) NestedProfileSections() []SectionInfo {
+// NestedSections lists SectionInfo of all nested sections that may be used inside the configuration
+func (t *TemplateInfoData) NestedSections() []SectionInfo {
 	sectionByType := make(map[string]*namedPropertySet)
 
+	t.collectPropertiesByType(t.Global, sectionByType)
+	t.collectPropertiesByType(t.Group, sectionByType)
 	t.collectPropertiesByType(t.Profile, sectionByType)
 	for _, section := range t.ProfileSections() {
 		t.collectPropertiesByType(section, sectionByType)

diff --git a/config/template_test.go b/config/template_test.go
@@ -443,10 +443,12 @@ func TestInfoData(t *testing.T) {
 
 	assert.NotEmpty(t, data.ProfileSections())
 
-	t.Run("NestedProfileSections", func(t *testing.T) {
-		sections := data.NestedProfileSections()
+	t.Run("NestedSections", func(t *testing.T) {
+		sections := data.NestedSections()
 		assert.NotEmpty(t, sections)
 		assert.Subset(t, collect.From(sections, SectionInfo.Name), []string{
+			"ScheduleBaseConfig",
+			"ScheduleConfig",
 			"SendMonitoringHeader",
 			"SendMonitoringSection",
 			"StreamErrorSection",

diff --git a/contrib/templates/config-reference.gomd b/contrib/templates/config-reference.gomd
@@ -72,6 +72,7 @@ date: {{ .Now.Format "2006-01-02T15:04:05Z07:00" }}
     {{- /*gotype: github.com/creativeprojects/resticprofile/config.PropertyInfo*/ -}}
     {{- $more := 0 -}}
     {{- $single := .IsSingle -}}
+    {{- $singlePropertySet := .IsSinglePropertySet -}}
     {{- if .CanBeBool -}}
       `true` / `false`
       {{- $more = 1 -}}
@@ -98,7 +99,7 @@ date: {{ .Now.Format "2006-01-02T15:04:05Z07:00" }}
         {{- if $more }} OR {{ end -}}
         {{- with .PropertySet -}}
             {{- if .TypeName -}}
-                {{- if not $single }} one or more {{ end -}}
+                {{- if not $singlePropertySet }} one or more {{ end -}}
                 nested *[{{ .TypeName }}](#nested-{{ .TypeName | lower }})*
             {{- else -}}
                 {{- if .OtherPropertyInfo -}}
@@ -187,7 +188,7 @@ The configuration file reference is generated from resticprofile's data model an
     * [Section profile\.<strong>{{ .Name }}</strong>](#section-profile{{ .Name | lower }})
 {{- end }}
   * [Nested profile sections](#nested-profile-sections)
-{{- range .NestedProfileSections }}
+{{- range .NestedSections }}
     * [Nested <em>{{ .Name }}</em>](#nested-{{ .Name | lower }})
 {{- end }}
   * [Section <strong>groups</strong>](#section-groups)
@@ -277,7 +278,7 @@ can be overridden in this section.
 Nested sections describe configuration structure that is assigned to flags within the
 configuration, see [HTTP Hooks]({{- $configWebUrl -}}/http_hooks/) as an example.
 
-{{ range .NestedProfileSections -}}{{ $layoutHeadings -}}### Nested *{{ .Name }}*
+{{ range .NestedSections -}}{{ $layoutHeadings -}}### Nested *{{ .Name }}*
 
 {{ .Description }}