docs: add comments to default configuration

author: Alan Pearce 2024-05-20 19:57:13 +0200
committer: Alan Pearce 2024-05-20 19:57:13 +0200
commit: 12d5d45a7894c3f6b6d598f9447de839d31436ef (patch)
tree: 179d57e1bf998184db3ee2df121904a37240356b
parent: a90419aa46ec42588f65e6327559ce479f9c5b67 (diff)
download: searchix-12d5d45a7894c3f6b6d598f9447de839d31436ef.tar.lz
searchix-12d5d45a7894c3f6b6d598f9447de839d31436ef.tar.zst
searchix-12d5d45a7894c3f6b6d598f9447de839d31436ef.zip
5 files changed, 121 insertions, 48 deletions
diff --git a/defaults.toml b/defaults.toml
index 38aa421..c651508 100644
--- a/defaults.toml
+++ b/defaults.toml
@@ -1,14 +1,24 @@
+# Path to store index data.
 DataPath = './data'
+# How much information to log, one of 'debug', 'info', 'warn', 'error'.
 LogLevel = 'INFO'
 
+# Settings for the web server
 [Web]
+# Which address or hostname to listen on. IPv6 addresses need square brackets.
 ListenAddress = 'localhost'
+# Port number to listen on.
 Port = 3000
+# Absolute URL to this instance, useful if behind a reverse proxy
 BaseURL = 'http://localhost:3000'
+# If set, will send server errors to Sentry
 SentryDSN = ''
+# Affects logging parameters. One of 'development' or 'production'
 Environment = 'development'
+# Content to add to HTML <head>. Can be used to override styling, add scripts, etc.
 ExtraHeadHTML = ''
 
+# Content-Security-Policy header to send with requests. Should only need changing if ExtraHeadHTML is used.
 [Web.ContentSecurityPolicy]
 base-uri = []
 block-all-mixed-content = false
@@ -42,90 +52,146 @@ trusted-types = []
 upgrade-insecure-requests = false
 worker-src = []
 
+# Extra headers to send with HTTP requests
 [Web.Headers]
 x-content-type-options = 'nosniff'
 
+# Settings for the import job
 [Importer]
+# Abort fetch and import process for all jobs if it takes longer than this value.
 Timeout = '30m0s'
+# Local time of day to run fetch/import process
 UpdateAt = '04:00:00'
 
 [Importer.Sources]
 [Importer.Sources.darwin]
+# Human-readable name of source for generating links
 Name = 'Darwin'
+# Machine-readable name of source. Must be URL- and path-safe.
 Key = 'darwin'
+# Controls whether to show in the web interface and to run fetch/import jobs.
 Enable = false
+# How to fetch options.json. One of 'channel', 'channel-nixpkgs' or 'download'.
 Fetcher = 'channel'
+# Kind of data available from source. Currently supports 'packages' and 'options'.
 Importer = 'options'
+# (Fetcher=channel) Local name for channel, (Fetcher=channel-nixpkgs) Remote name of channel.
 Channel = 'darwin'
+# (Fetcher=channel) Remote URL for channel, (Fetcher=download) Path containing files named 'revision' and 'options.json'.
 URL = 'https://github.com/LnL7/nix-darwin/archive/master.tar.gz'
+# (Fetcher=channel) Nix attribute name (i.e. nix-build -A) that builds an {options,packages}.json
 Attribute = 'options'
+# (Fetcher=channel) Sub-path of imported channel which contains the attribute above, e.g. release.nix
 ImportPath = 'release.nix'
+# Abort fetch if it takes longer than this.
 FetchTimeout = '5m0s'
+# Abort import if it takes longer than this.
 ImportTimeout = '15m0s'
+# (Fetcher=channel) Path under ./result symlink to folder containing {options,packages}.json.
 OutputPath = 'share/doc/darwin'
 
+# Used to generate declaration/definition links
 [Importer.Sources.darwin.Repo]
+# Currently only 'github' is supported.
 Type = 'github'
 Owner = 'LnL7'
 Repo = 'nix-darwin'
-Revision = ''
 
 [Importer.Sources.home-manager]
+# Human-readable name of source for generating links
 Name = 'Home Manager'
+# Machine-readable name of source. Must be URL- and path-safe.
 Key = 'home-manager'
+# Controls whether to show in the web interface and to run fetch/import jobs.
 Enable = false
+# How to fetch options.json. One of 'channel', 'channel-nixpkgs' or 'download'.
 Fetcher = 'channel'
+# Kind of data available from source. Currently supports 'packages' and 'options'.
 Importer = 'options'
+# (Fetcher=channel) Local name for channel, (Fetcher=channel-nixpkgs) Remote name of channel.
 Channel = 'home-manager'
+# (Fetcher=channel) Remote URL for channel, (Fetcher=download) Path containing files named 'revision' and 'options.json'.
 URL = 'https://github.com/nix-community/home-manager/archive/master.tar.gz'
+# (Fetcher=channel) Nix attribute name (i.e. nix-build -A) that builds an {options,packages}.json
 Attribute = 'docs.json'
+# (Fetcher=channel) Sub-path of imported channel which contains the attribute above, e.g. release.nix
 ImportPath = 'default.nix'
+# Abort fetch if it takes longer than this.
 FetchTimeout = '5m0s'
+# Abort import if it takes longer than this.
 ImportTimeout = '15m0s'
+# (Fetcher=channel) Path under ./result symlink to folder containing {options,packages}.json.
 OutputPath = 'share/doc/home-manager'
 
+# Used to generate declaration/definition links
 [Importer.Sources.home-manager.Repo]
+# Currently only 'github' is supported.
 Type = 'github'
 Owner = 'nix-community'
 Repo = 'home-manager'
-Revision = ''
 
 [Importer.Sources.nixos]
+# Human-readable name of source for generating links
 Name = 'NixOS'
+# Machine-readable name of source. Must be URL- and path-safe.
 Key = 'nixos'
+# Controls whether to show in the web interface and to run fetch/import jobs.
 Enable = true
+# How to fetch options.json. One of 'channel', 'channel-nixpkgs' or 'download'.
 Fetcher = 'channel'
+# Kind of data available from source. Currently supports 'packages' and 'options'.
 Importer = 'options'
+# (Fetcher=channel) Local name for channel, (Fetcher=channel-nixpkgs) Remote name of channel.
 Channel = 'nixpkgs'
+# (Fetcher=channel) Remote URL for channel, (Fetcher=download) Path containing files named 'revision' and 'options.json'.
 URL = 'https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz'
+# (Fetcher=channel) Nix attribute name (i.e. nix-build -A) that builds an {options,packages}.json
 Attribute = 'options'
+# (Fetcher=channel) Sub-path of imported channel which contains the attribute above, e.g. release.nix
 ImportPath = 'nixos/release.nix'
+# Abort fetch if it takes longer than this.
 FetchTimeout = '5m0s'
+# Abort import if it takes longer than this.
 ImportTimeout = '15m0s'
+# (Fetcher=channel) Path under ./result symlink to folder containing {options,packages}.json.
 OutputPath = 'share/doc/nixos'
 
+# Used to generate declaration/definition links
 [Importer.Sources.nixos.Repo]
+# Currently only 'github' is supported.
 Type = 'github'
 Owner = 'NixOS'
 Repo = 'nixpkgs'
-Revision = ''
 
 [Importer.Sources.nixpkgs]
+# Human-readable name of source for generating links
 Name = 'Nix Packages'
+# Machine-readable name of source. Must be URL- and path-safe.
 Key = 'nixpkgs'
+# Controls whether to show in the web interface and to run fetch/import jobs.
 Enable = true
+# How to fetch options.json. One of 'channel', 'channel-nixpkgs' or 'download'.
 Fetcher = 'channel-nixpkgs'
+# Kind of data available from source. Currently supports 'packages' and 'options'.
 Importer = 'packages'
+# (Fetcher=channel) Local name for channel, (Fetcher=channel-nixpkgs) Remote name of channel.
 Channel = 'nixos-unstable'
+# (Fetcher=channel) Remote URL for channel, (Fetcher=download) Path containing files named 'revision' and 'options.json'.
 URL = ''
+# (Fetcher=channel) Nix attribute name (i.e. nix-build -A) that builds an {options,packages}.json
 Attribute = ''
+# (Fetcher=channel) Sub-path of imported channel which contains the attribute above, e.g. release.nix
 ImportPath = ''
+# Abort fetch if it takes longer than this.
 FetchTimeout = '5m0s'
+# Abort import if it takes longer than this.
 ImportTimeout = '15m0s'
+# (Fetcher=channel) Path under ./result symlink to folder containing {options,packages}.json.
 OutputPath = 'packages.json.br'
 
+# Used to generate declaration/definition links
 [Importer.Sources.nixpkgs.Repo]
+# Currently only 'github' is supported.
 Type = 'github'
 Owner = 'NixOS'
 Repo = 'nixpkgs'
-Revision = ''
diff --git a/internal/config/config.go b/internal/config/config.go
index 9ab7ab5..a0a05eb 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -1,7 +1,6 @@
 package config
 
 import (
-	"html/template"
 	"log/slog"
 	"maps"
 	"net/url"
@@ -94,30 +93,6 @@ func mustLocalTime(in string) (time LocalTime) {
 	return
 }
 
-type Web struct {
-	ContentSecurityPolicy CSP
-	ListenAddress         string
-	Port                  int
-	BaseURL               URL
-	SentryDSN             string
-	Environment           string
-	ExtraHeadHTML         template.HTML
-	Headers               map[string]string
-}
-
-type Importer struct {
-	Sources  map[string]*Source
-	Timeout  Duration
-	UpdateAt LocalTime
-}
-
-type Config struct {
-	DataPath string
-	LogLevel slog.Level
-	Web      *Web
-	Importer *Importer
-}
-
 var nixpkgs = Repository{
 	Type:  "github",
 	Owner: "NixOS",
diff --git a/internal/config/repository.go b/internal/config/repository.go
index 957cad4..44d8251 100644
--- a/internal/config/repository.go
+++ b/internal/config/repository.go
@@ -13,10 +13,10 @@ const (
 )
 
 type Repository struct {
-	Type     string `default:"github"`
+	Type     string `toml:""  default:"github" comment:"Currently only 'github' is supported."`
 	Owner    string
 	Repo     string
-	Revision string
+	Revision string `toml:"-"`
 }
 
 func (f RepoType) String() string {
diff --git a/internal/config/source.go b/internal/config/source.go
deleted file mode 100644
index 15b1aa0..0000000
--- a/internal/config/source.go
+++ /dev/null
@@ -1,17 +0,0 @@
-package config
-
-type Source struct {
-	Name          string
-	Key           string
-	Enable        bool
-	Fetcher       Fetcher
-	Importer      ImporterType
-	Channel       string
-	URL           string
-	Attribute     string
-	ImportPath    string
-	FetchTimeout  Duration
-	ImportTimeout Duration
-	OutputPath    string
-	Repo          Repository
-}
diff --git a/internal/config/structs.go b/internal/config/structs.go
new file mode 100644
index 0000000..4137261
--- /dev/null
+++ b/internal/config/structs.go
@@ -0,0 +1,49 @@
+//nolint:lll
+package config
+
+// keep config structs here so that lll ignores the long lines (go doesn't support multi-line struct tags)
+
+import (
+	"html/template"
+	"log/slog"
+)
+
+type Config struct {
+	DataPath string     `comment:"Path to store index data."`
+	LogLevel slog.Level `comment:"How much information to log, one of 'debug', 'info', 'warn', 'error'."`
+	Web      *Web       `comment:"Settings for the web server"`
+	Importer *Importer  `comment:"Settings for the import job"`
+}
+
+type Web struct {
+	ContentSecurityPolicy CSP               `comment:"Content-Security-Policy header to send with requests. Should only need changing if ExtraHeadHTML is used."`
+	ListenAddress         string            `comment:"Which address or hostname to listen on. IPv6 addresses need square brackets."`
+	Port                  int               `comment:"Port number to listen on."`
+	BaseURL               URL               `comment:"Absolute URL to this instance, useful if behind a reverse proxy"`
+	SentryDSN             string            `comment:"If set, will send server errors to Sentry"`
+	Environment           string            `comment:"Affects logging parameters. One of 'development' or 'production'"`
+	ExtraHeadHTML         template.HTML     `comment:"Content to add to HTML <head>. Can be used to override styling, add scripts, etc."`
+	Headers               map[string]string `comment:"Extra headers to send with HTTP requests"`
+}
+
+type Importer struct {
+	Sources  map[string]*Source
+	Timeout  Duration  `comment:"Abort fetch and import process for all jobs if it takes longer than this value."`
+	UpdateAt LocalTime `comment:"Local time of day to run fetch/import process"`
+}
+
+type Source struct {
+	Name          string       `comment:"Human-readable name of source for generating links"`
+	Key           string       `comment:"Machine-readable name of source. Must be URL- and path-safe."`
+	Enable        bool         `comment:"Controls whether to show in the web interface and to run fetch/import jobs."`
+	Fetcher       Fetcher      `comment:"How to fetch options.json. One of 'channel', 'channel-nixpkgs' or 'download'."`
+	Importer      ImporterType `comment:"Kind of data available from source. Currently supports 'packages' and 'options'."`
+	Channel       string       `comment:"(Fetcher=channel) Local name for channel, (Fetcher=channel-nixpkgs) Remote name of channel."`
+	URL           string       `comment:"(Fetcher=channel) Remote URL for channel, (Fetcher=download) Path containing files named 'revision' and 'options.json'."`
+	Attribute     string       `comment:"(Fetcher=channel) Nix attribute name (i.e. nix-build -A) that builds an {options,packages}.json"`
+	ImportPath    string       `comment:"(Fetcher=channel) Sub-path of imported channel which contains the attribute above, e.g. release.nix"`
+	FetchTimeout  Duration     `comment:"Abort fetch if it takes longer than this."`
+	ImportTimeout Duration     `comment:"Abort import if it takes longer than this."`
+	OutputPath    string       `comment:"(Fetcher=channel) Path under ./result symlink to folder containing {options,packages}.json."`
+	Repo          Repository   `comment:"Used to generate declaration/definition links"`
+}
author	Alan Pearce	2024-05-20 19:57:13 +0200
committer	Alan Pearce	2024-05-20 19:57:13 +0200
commit	12d5d45a7894c3f6b6d598f9447de839d31436ef (patch)
tree	179d57e1bf998184db3ee2df121904a37240356b
parent	a90419aa46ec42588f65e6327559ce479f9c5b67 (diff)
download	searchix-12d5d45a7894c3f6b6d598f9447de839d31436ef.tar.lz searchix-12d5d45a7894c3f6b6d598f9447de839d31436ef.tar.zst searchix-12d5d45a7894c3f6b6d598f9447de839d31436ef.zip