docs: add comments to default configuration
Alan Pearce alan@alanpearce.eu
Mon, 20 May 2024 19:57:13 +0200
5 files changed, 121 insertions(+), 48 deletions(-)
M defaults.toml → 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 = ''
M internal/config/config.go → internal/config/config.go
@@ -1,7 +1,6 @@ package config import ( - "html/template" "log/slog" "maps" "net/url" @@ -92,30 +91,6 @@ panic(errors.Errorf("Could not parse time: %s", in)) } 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{
M internal/config/repository.go → internal/config/repository.go
@@ -13,10 +13,10 @@ GitHub ) 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 {
D internal/config/source.go
@@ -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 -}
A 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"` +}