diff --git a/docs/.gitignore b/docs/.gitignore index e35d8850..e5e3ff7d 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ _build +*-options.json diff --git a/docs/conf.py b/docs/conf.py index 852aff42..e723fc36 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,6 +16,8 @@ copyright = "The EPNix Contributors" author = "The EPNix Contributors" +source_repository = "https://github.com/epics-extensions/EPNix" + language = "en" nitpicky = True @@ -27,6 +29,7 @@ "myst_parser", "sphinx.ext.githubpages", "sphinx_copybutton", + "sphinxcontrib_nixdomain", ] templates_path = ["_templates"] @@ -69,6 +72,13 @@ # Exclude copying line numbers, prompts, and prompt outputs copybutton_exclude = ".linenos, .gp, .go" +# -- Options for the Nix domain ---------------------------------------------- + +nix_options_json_files = ["./nixos-options.json"] + +def nix_linkcode_resolve(path: str) -> str: + return f"{source_repository}/blob/master/{path}" + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output @@ -77,7 +87,7 @@ html_theme = "furo" html_theme_options = { - "source_repository": "https://github.com/epics-extensions/EPNix", + "source_repository": source_repository, "source_branch": "master", "source_directory": "docs/", "dark_css_variables": { @@ -91,7 +101,7 @@ "footer_icons": [ { "name": "GitHub", - "url": "https://github.com/epics-extensions/EPNix", + "url": source_repository, "html": """ @@ -111,7 +121,7 @@ man_pages = [ ("ioc/references/options", "epnix-ioc", "IOC options reference", "", 5), ("ioc/references/packages", "epnix-ioc-packages", "", "", 5), - ("nixos-services/options", "epnix-nixos", "", "", 5), + ("nixos-services/options-reference/index", "epnix-nixos", "", "", 5), ("pkgs/packages", "epnix-packages", "", "", 5), ] diff --git a/docs/index.rst b/docs/index.rst index 1d0dde55..b21dc460 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -97,7 +97,7 @@ This documentation follows the `Diátaxis`_ documentation framework. nixos-services/index nixos-services/tutorials/index nixos-services/user-guides/index - nixos-services/options + nixos-services/options-reference/index .. toctree:: :caption: Release notes diff --git a/docs/nixos-services/options-reference/archiver-appliance.rst b/docs/nixos-services/options-reference/archiver-appliance.rst new file mode 100644 index 00000000..db7e4019 --- /dev/null +++ b/docs/nixos-services/options-reference/archiver-appliance.rst @@ -0,0 +1,4 @@ +Archiver Appliance +================== + +.. nix:automodule:: services.archiver-appliance diff --git a/docs/nixos-services/options-reference/ca-gateway.rst b/docs/nixos-services/options-reference/ca-gateway.rst new file mode 100644 index 00000000..1aac575f --- /dev/null +++ b/docs/nixos-services/options-reference/ca-gateway.rst @@ -0,0 +1,4 @@ +Channel Access gateway +====================== + +.. nix:automodule:: services.ca-gateway diff --git a/docs/nixos-services/options-reference/channel-finder.rst b/docs/nixos-services/options-reference/channel-finder.rst new file mode 100644 index 00000000..32cdcd35 --- /dev/null +++ b/docs/nixos-services/options-reference/channel-finder.rst @@ -0,0 +1,4 @@ +Channel Finder +============== + +.. nix:automodule:: services.channel-finder diff --git a/docs/nixos-services/options-reference/index.rst b/docs/nixos-services/options-reference/index.rst new file mode 100644 index 00000000..52760437 --- /dev/null +++ b/docs/nixos-services/options-reference/index.rst @@ -0,0 +1,8 @@ +Options reference +================= + +.. toctree:: + :titlesonly: + :glob: + + * diff --git a/docs/nixos-services/options-reference/phoebus-alarm-logger.rst b/docs/nixos-services/options-reference/phoebus-alarm-logger.rst new file mode 100644 index 00000000..bde84793 --- /dev/null +++ b/docs/nixos-services/options-reference/phoebus-alarm-logger.rst @@ -0,0 +1,4 @@ +Phoebus alarm logger +==================== + +.. nix:automodule:: services.phoebus-alarm-logger diff --git a/docs/nixos-services/options-reference/phoebus-alarm-server.rst b/docs/nixos-services/options-reference/phoebus-alarm-server.rst new file mode 100644 index 00000000..c5b6491d --- /dev/null +++ b/docs/nixos-services/options-reference/phoebus-alarm-server.rst @@ -0,0 +1,4 @@ +Phoebus alarm server +==================== + +.. nix:automodule:: services.phoebus-alarm-server diff --git a/docs/nixos-services/options-reference/phoebus-olog.rst b/docs/nixos-services/options-reference/phoebus-olog.rst new file mode 100644 index 00000000..5e7347b2 --- /dev/null +++ b/docs/nixos-services/options-reference/phoebus-olog.rst @@ -0,0 +1,4 @@ +Phoebus Olog +============ + +.. nix:automodule:: services.phoebus-olog diff --git a/docs/nixos-services/options-reference/phoebus-save-and-restore.rst b/docs/nixos-services/options-reference/phoebus-save-and-restore.rst new file mode 100644 index 00000000..08469d0a --- /dev/null +++ b/docs/nixos-services/options-reference/phoebus-save-and-restore.rst @@ -0,0 +1,4 @@ +Phoebus save-and-restore +======================== + +.. nix:automodule:: services.phoebus-save-and-restore diff --git a/docs/nixos-services/options-reference/recceiver.rst b/docs/nixos-services/options-reference/recceiver.rst new file mode 100644 index 00000000..4caf6130 --- /dev/null +++ b/docs/nixos-services/options-reference/recceiver.rst @@ -0,0 +1,4 @@ +RecCeiver +========= + +.. nix:automodule:: services.recceiver diff --git a/docs/nixos-services/tutorials/archiver-appliance.rst b/docs/nixos-services/tutorials/archiver-appliance.rst index 5c1203a7..cd784c41 100644 --- a/docs/nixos-services/tutorials/archiver-appliance.rst +++ b/docs/nixos-services/tutorials/archiver-appliance.rst @@ -92,7 +92,7 @@ you can read the `Nixpkgs preface`_. Having the ``epnix`` input is what’s going to enable you to use :doc:`packages from EPNix <../../pkgs/packages>`, such as Archiver Appliance. -It also enables you to use :doc:`EPNix' extra NixOS options <../options>`, +It also enables you to use :doc:`EPNix' extra NixOS options <../options-reference/index>`, such as the options configuring Tomcat, the systemd service, the ``archappl`` user and group, MariaDB, and so on. .. _Nix flake command manual: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html @@ -141,11 +141,11 @@ you will see a helpful error message: is used but not defined. (use '--show-trace' to show detailed location information) -This tells you that setting the ``services.archiver-appliance.stores.lts.location`` option is mandatory, +This tells you that setting the :nix:option:`services.archiver-appliance.stores.lts.location` option is mandatory, but we didn’t set any value. To figure out what this option is about, -you can examine the :doc:`options reference <../options>`. +you can examine the :doc:`../options-reference/archiver-appliance` reference. The options reference gives a description for this option: @@ -348,7 +348,7 @@ For example: }; } -See the :ref:`sts.size option ` in the reference for a more in-depth description. +See the :nix:option:`services.archiver-appliance.stores.sts.size` option in the reference for a more in-depth description. Restricting access ~~~~~~~~~~~~~~~~~~ diff --git a/docs/nixos-services/user-guides/channel-finder.rst b/docs/nixos-services/user-guides/channel-finder.rst index 5cfddc2f..e7cb7f43 100644 --- a/docs/nixos-services/user-guides/channel-finder.rst +++ b/docs/nixos-services/user-guides/channel-finder.rst @@ -21,7 +21,7 @@ ChannelFinder service --------------------- To enable the ChannelFinder service, -use :ref:`opt-services.channel-finder.enable` and related options. +use :nix:option:`services.channel-finder.enable` and related options. You will also need to enable ElasticSearch. For example: @@ -65,7 +65,7 @@ You can open your browser at http://localhost:8082/ to see the ChannelFinder adm For more settings, examine the `ChannelFinder configuration`_ reference -and the :ref:`opt-services.channel-finder.settings` option. +and the :nix:option:`services.channel-finder.settings` option. .. _ChannelFinder configuration: https://channelfinder.readthedocs.io/en/latest/config.html @@ -163,8 +163,8 @@ and use the ``settings`` option for configuring all other settings. For a list of available ``settings``, examine the `RecCeiver demo.conf`_ file. -Also examine the :ref:`opt-services.recceiver.channelfinderapi` -and :ref:`opt-services.recceiver.settings` options. +Also examine the :nix:option:`services.recceiver.channelfinderapi` +and :nix:option:`services.recceiver.settings` options. TODO: explain which cf role is needed diff --git a/docs/release-notes/2405.rst b/docs/release-notes/2405.rst index 6debc952..4acec079 100644 --- a/docs/release-notes/2405.rst +++ b/docs/release-notes/2405.rst @@ -1,6 +1,8 @@ 24.05 Release notes =================== +.. default-domain:: nix + .. role:: nix(code) :language: nix @@ -10,9 +12,9 @@ Breaking changes - The :nix:`config.epnix.outputs.mdbook` and :nix:`config.epnix.outputs.manpages` options from the IOC module options, previously deprecated, are now removed. -- The :ref:`opt-services.phoebus-alarm-server.enable`, - :ref:`opt-services.phoebus-olog.enable`, - and :ref:`opt-services.phoebus-save-and-restore.enable` options +- The :option:`services.phoebus-alarm-server.enable`, + :option:`services.phoebus-olog.enable`, + and :option:`services.phoebus-save-and-restore.enable` options don't enable ElasticSearch automatically anymore. See :doc:`../nixos-services/user-guides/phoebus-alarm` and :doc:`../nixos-services/user-guides/phoebus-save-and-restore` diff --git a/flake.lock b/flake.lock index 38d4c54c..d511e482 100644 --- a/flake.lock +++ b/flake.lock @@ -72,6 +72,33 @@ "type": "github" } }, + "mdbook-nixdoc": { + "inputs": { + "nix-github-actions": [ + "sphinxcontrib-nixdomain", + "pyproject-nix", + "nix-github-actions" + ], + "nixpkgs": [ + "sphinxcontrib-nixdomain", + "pyproject-nix", + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1708395692, + "narHash": "sha256-smf0VmxGbjJDZqKvxxG3ZVqubgbVwAWG26wPo+BT/A0=", + "owner": "adisbladis", + "repo": "mdbook-nixdoc", + "rev": "d6a71b114b9221c0b4f20d31b81766d072cc26be", + "type": "github" + }, + "original": { + "owner": "adisbladis", + "repo": "mdbook-nixdoc", + "type": "github" + } + }, "nix-github-actions": { "inputs": { "nixpkgs": [ @@ -93,6 +120,28 @@ "type": "github" } }, + "nix-github-actions_2": { + "inputs": { + "nixpkgs": [ + "sphinxcontrib-nixdomain", + "pyproject-nix", + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1703863825, + "narHash": "sha256-rXwqjtwiGKJheXB43ybM8NwWB8rO2dSRrEqes0S7F5Y=", + "owner": "nix-community", + "repo": "nix-github-actions", + "rev": "5163432afc817cf8bd1f031418d1869e4c9d5547", + "type": "github" + }, + "original": { + "owner": "nix-community", + "repo": "nix-github-actions", + "type": "github" + } + }, "nixpkgs": { "locked": { "lastModified": 1728067476, @@ -133,12 +182,57 @@ "type": "github" } }, + "pyproject-nix": { + "inputs": { + "mdbook-nixdoc": "mdbook-nixdoc", + "nix-github-actions": "nix-github-actions_2", + "nixpkgs": [ + "sphinxcontrib-nixdomain", + "nixpkgs" + ] + }, + "locked": { + "lastModified": 1721039766, + "narHash": "sha256-8H5z3bAOP5ukdXxSAisg6A1pdOJO2RwuJTsGTS3kpbk=", + "owner": "nix-community", + "repo": "pyproject.nix", + "rev": "8783458df981ba04aa75fad5fc169fb906b1bc50", + "type": "github" + }, + "original": { + "owner": "nix-community", + "repo": "pyproject.nix", + "type": "github" + } + }, "root": { "inputs": { "bash-lib": "bash-lib", "flake-utils": "flake-utils_2", "nixpkgs": "nixpkgs", - "poetry2nix": "poetry2nix" + "poetry2nix": "poetry2nix", + "sphinxcontrib-nixdomain": "sphinxcontrib-nixdomain" + } + }, + "sphinxcontrib-nixdomain": { + "inputs": { + "nixpkgs": [ + "nixpkgs" + ], + "pyproject-nix": "pyproject-nix" + }, + "locked": { + "lastModified": 1727724513, + "narHash": "sha256-yXWzoUpoDpboHyuE12UZEmefSj4nb7pHUcepP5CPWJY=", + "owner": "minijackson", + "repo": "sphinxcontrib-nixdomain", + "rev": "62d8bb399d607404258a77b0010394d3b9173c2e", + "type": "github" + }, + "original": { + "owner": "minijackson", + "repo": "sphinxcontrib-nixdomain", + "type": "github" } }, "systems": { diff --git a/flake.nix b/flake.nix index ad1f8c11..7ecdb450 100644 --- a/flake.nix +++ b/flake.nix @@ -12,6 +12,10 @@ url = "github:nix-community/poetry2nix"; inputs.nixpkgs.follows = "nixpkgs"; }; + sphinxcontrib-nixdomain = { + url = "github:minijackson/sphinxcontrib-nixdomain"; + inputs.nixpkgs.follows = "nixpkgs"; + }; }; outputs = { @@ -20,7 +24,7 @@ nixpkgs, ... } @ inputs: let - overlay = import ./pkgs self.lib; + overlay = import ./pkgs self.lib inputs; systemDependentOutputs = system: let pkgs = import nixpkgs { @@ -29,6 +33,7 @@ overlay inputs.bash-lib.overlay inputs.poetry2nix.overlays.default + inputs.sphinxcontrib-nixdomain.overlays.default ]; }; in { diff --git a/lib/default.nix b/lib/default.nix index 38ed4520..3fbcc959 100644 --- a/lib/default.nix +++ b/lib/default.nix @@ -6,6 +6,8 @@ } @ args: with lib; let self = { + inherit inputs; + documentation = import ./documentation.nix args; evaluation = import ./evaluation.nix args; formats = import ./formats.nix args; diff --git a/nixos/modules/archiver-appliance.nix b/nixos/modules/archiver-appliance.nix index 6ba9db6f..020813ce 100644 --- a/nixos/modules/archiver-appliance.nix +++ b/nixos/modules/archiver-appliance.nix @@ -83,7 +83,7 @@ in { enable = lib.mkEnableOption '' Archiver Appliance. - Archiver Appliance will listen on port 8080''; + Archiver Appliance listens on port 8080''; package = lib.mkOption { description = "Archiver Appliance package to use."; @@ -97,7 +97,8 @@ in { description = '' Open the firewall for the Archiver Appliance service. - Warning: this opens the firewall on all network interfaces. + .. warning:: + This opens the firewall on all network interfaces. ''; type = lib.types.bool; default = false; @@ -105,11 +106,11 @@ in { appliancesXml = lib.mkOption { description = '' - Content of the `appliances.xml` file. + Content of the :file:`appliances.xml` file. - See the [ARCHAPPL_APPLIANCES documentation] for more details. + See the `appliances.xml documentation`_ for more details. - [ARCHAPPL_APPLIANCES documentation]: https://slacmshankar.github.io/epicsarchiver_docs/api/org/epics/archiverappliance/config/ConfigService.html#ARCHAPPL_APPLIANCES + .. _appliances.xml documentation: https://epicsarchiver.readthedocs.io/en/latest/sysadmin/installguide.html#appliances-xml ''; type = lib.types.str; default = defaultAppliancesXml; @@ -129,13 +130,12 @@ in { description = '' The identity of the current appliance. - If you change this value, you will need to modify the content of - `appliances.xml`: the specified identity must match an identity - of one of the appliance XML elements. + If you change this value, + you will need to modify the content of :file:`appliances.xml`: + the specified identity must match an identity of one of the appliance XML elements. - See the [ARCHAPPL_MYIDENTITY documentation] for more details. - - [ARCHAPPL_MYIDENTITY documentation]: https://slacmshankar.github.io/epicsarchiver_docs/api/org/epics/archiverappliance/config/ConfigService.html#ARCHAPPL_MYIDENTITY + .. seealso:: + :nix:option:`services.archiver-appliance.appliancesXml` ''; type = lib.types.str; default = "appliance0"; @@ -143,11 +143,11 @@ in { ARCHAPPL_APPLIANCES = lib.mkOption { description = '' - Path to an `appliances.xml` file. + Path to an :file:`appliances.xml` file. - By default this NixOS module will generate a file from the - `appliancesXml` option, so you might want to modify the - `appliancesXml` option instead. + By default this NixOS module will generate a file + from the :nix:option:`services.archiver-appliance.appliancesXml` option, + so you might want to modify that instead. ''; type = lib.types.path; default = pkgs.writeText "appliances.xml" cfg.appliancesXml; @@ -156,14 +156,15 @@ in { ARCHAPPL_POLICIES = lib.mkOption { description = '' - Path to a `policies.py` file. + Path to a :file:`policies.py` file. - This file specifies the various policies that can be used when - archiving a PV. For example, you can specify that a given policy - archive PVs at a rate of 2Hz. + This file specifies the various policies + that can be used when archiving a PV. + For example, + you can specify that a given policy archives PVs at a rate of 2Hz. - By default, the `policies.py` found in - `src/sitespecific/tests/classpathfiles/policies.py` is used. + By default, + the :file:`policies.py` found in :file:`src/sitespecific/tests/classpathfiles/policies.py` is used. ''; type = lib.types.path; default = "${cfg.package}/share/archappl/policies.py"; @@ -196,8 +197,8 @@ in { EPICS_CA_AUTO_ADDR_LIST = lib.mkOption { description = '' - If set, behave as if every broadcast address of every network - interface is added to EPICS_CA_ADDR_LIST. + If set, + behave as if every broadcast address of every network interface is added to ``EPICS_CA_ADDR_LIST``. ''; type = lib.types.bool; default = true; @@ -211,9 +212,10 @@ in { description = '' List of Channel Access destination IP addresses. - Each IP address can be a unicast address, or a broadcast address. + Each IP address can be a unicast address, + or a broadcast address. - This option is ignored of EPICS_CA_AUTO_ADDR_LIST is enabled (the default). + This option is ignored of ``EPICS_CA_AUTO_ADDR_LIST`` is enabled (the default). ''; type = with lib.types; listOf str; default = []; @@ -227,8 +229,7 @@ in { stores = { configure = lib.mkOption { description = '' - Whether to automatically configure the local STS, MTS, and LTS - directories. + Whether to automatically configure the local STS, MTS, and LTS directories. ''; type = lib.types.bool; default = true; @@ -238,11 +239,13 @@ in { description = '' Size of the STS in bytes. - If null, the size will depend on the amount of RAM available, + If null, + the size will depend on the amount of RAM available, normally half of your physical RAM without swap. - Warning: If you oversize it, the machine will deadlock since the - OOM handler will not be able to free that memory. + .. warning:: + If you oversize it, + the machine will deadlock since the OOM handler will not be able to free that memory. ''; example = "20g"; type = with lib.types; nullOr str; diff --git a/nixos/modules/ca-gateway.nix b/nixos/modules/ca-gateway.nix index 4716a3d1..fee5de3d 100644 --- a/nixos/modules/ca-gateway.nix +++ b/nixos/modules/ca-gateway.nix @@ -22,7 +22,8 @@ in { description = '' Open the firewall for allowing Channel Access communications. - Warning: this opens the firewall on all network interfaces. + .. warning:: + This opens the firewall on all network interfaces. ''; type = lib.types.bool; default = false; @@ -35,7 +36,7 @@ in { These options are passed onto the gateway command-line. Available options can be seen here: - + https://epics.anl.gov/EpicsDocumentation/ExtensionsManuals/Gateway/Gateway.html#Starting ''; default = {}; type = lib.types.submodule { @@ -56,7 +57,7 @@ in { See the sample file gateway.pvlist in the source distribution for a description of how to create this file: - + https://github.com/epics-extensions/ca-gateway/blob/v${pkg.version}/example/GATEWAY.pvlist ''; type = with lib.types; nullOr (either path str); default = null; @@ -81,7 +82,7 @@ in { See the sample file gateway.pvlist in the source distribution: - + https://github.com/epics-extensions/ca-gateway/blob/v${pkg.version}/example/GATEWAY.access ''; type = with lib.types; nullOr (either path str); default = null; @@ -98,9 +99,10 @@ in { description = '' IP address list that gateway's CA server listens for PV requests. - Sets env variable `EPICS_CAS_INTF_ADDR_LIST`. + Sets env variable ``EPICS_CAS_INTF_ADDR_LIST``. - By default, the CA server is accessible from all network interfaces configured into its host. + By default, + the CA server is accessible from all network interfaces configured into its host. ''; type = with lib.types; nullOr (listOf str); default = null; @@ -111,7 +113,7 @@ in { description = '' IP address list that gateway's CA server ignores. - Sets env variable `EPICS_CAS_IGNORE_ADDR_LIST`. + Sets env variable ``EPICS_CAS_IGNORE_ADDR_LIST``. ''; type = with lib.types; nullOr (listOf str); default = null; @@ -122,7 +124,7 @@ in { description = '' The port which the gateway's CA server uses to listen for PV requests. - Sets environment variable `EPICS_CAS_SERVER_PORT`. + Sets environment variable ``EPICS_CAS_SERVER_PORT``. ''; type = lib.types.port; default = 5064; @@ -132,13 +134,14 @@ in { description = '' IP address list that the gateway's CA client uses to find the real PVs. - See CA reference manual. + See the CA reference manual. - This sets environment variables `EPICS_CA_AUTO_LIST=NO` and `EPICS_CA_ADDR_LIST`. + This sets environment variables ``EPICS_CA_AUTO_LIST=NO`` and ``EPICS_CA_ADDR_LIST``. - Note: if you intend to broadcast on a port other than 5064, - you will need change your firewall configuration - and accept incoming UDP packets with your *source* port. + .. note:: + If you intend to broadcast on a port other than 5064, + you will need change your firewall configuration + and accept incoming UDP packets with your *source* port. ''; type = with lib.types; nullOr (listOf str); default = null; @@ -149,9 +152,9 @@ in { description = '' The port which the gateway's CA client uses to find the real PVs. - Sets environment variable `EPICS_CA_SERVER_PORT`. + Sets environment variable ``EPICS_CA_SERVER_PORT``. - With `openFirewall = true`, + With ``openFirewall = true``, this option sets the port in the firewall rule for the CA broadcast reply. ''; type = lib.types.port; diff --git a/nixos/modules/channel-finder/recceiver.nix b/nixos/modules/channel-finder/recceiver.nix index 065d851c..470bbba5 100644 --- a/nixos/modules/channel-finder/recceiver.nix +++ b/nixos/modules/channel-finder/recceiver.nix @@ -27,7 +27,7 @@ in { Configuration for the ChannelFinder client. See upstream documentation for all supported options: - + https://github.com/ChannelFinder/pyCFClient?tab=readme-ov-file#configuration ''; default = {}; type = lib.types.submodule { @@ -59,7 +59,7 @@ in { Configuration for the RecCeiver service. See upstream documentation for all supported options: - + https://github.com/ChannelFinder/recsync/blob/${pkg.version}/server/demo.conf ''; default = {}; type = lib.types.submodule { @@ -99,20 +99,20 @@ in { description = '' Processing chain, sequence of plugin names. - Plugin names may be followed by an instance name (eg. `db:arbitrary`) + Plugin names may be followed by an instance name (eg. ``db:arbitrary``) which allows for more than one instance of a plugin with different configuration. Default plugins: - `show` - : Prints information to daemon log + ``show`` + Prints information to daemon log - `db` - : Stores in sqlite3 database + ``db`` + Stores in sqlite3 database - `cf` - : Stores in a ChannelFinder server + ``cf`` + Stores in a ChannelFinder server ''; }; }; @@ -128,10 +128,10 @@ in { }; apply = val: lib.concatStringsSep "," (lib.mapAttrsToList (k: v: "${k}:${v}") val); description = '' - Attribute set of `VARIABLE = "PropertyName";` + Attribute set of ``VARIABLE = "PropertyName";`` - Specifies which environment `VARIABLE`s to pass on to the ChannelFinder server, - and defining the corresponding `PropertyName`. + Specifies which environment ``VARIABLEs`` to pass on to the ChannelFinder server, + and defining the corresponding ``PropertyName``. ''; }; }; diff --git a/nixos/modules/channel-finder/service.nix b/nixos/modules/channel-finder/service.nix index bd915543..948ed3e6 100644 --- a/nixos/modules/channel-finder/service.nix +++ b/nixos/modules/channel-finder/service.nix @@ -16,9 +16,8 @@ in { description = '' Open the firewall for the ChannelFinder service. - ```{warning} - This opens the firewall on all network interfaces. - ``` + .. warning:: + This opens the firewall on all network interfaces. This option opens firewall for the HTTP/HTTPS API, and pvAccess server. @@ -31,12 +30,12 @@ in { description = '' Configuration for the ChannelFinder service. - These options will be put into a `.properties` file. + These options will be put into a ``.properties`` file. Note that options containing a "." must be quoted. See upstream documentation for all supported options: - + https://channelfinder.readthedocs.io/en/latest/config.html#application-properties ''; default = {}; type = lib.types.submodule { @@ -97,8 +96,8 @@ in { ChannelFinder will provide two users: - - `admin:adminPass` - - `user:userPass` + - ``admin:adminPass`` + - ``user:userPass`` ''; }; diff --git a/nixos/modules/phoebus/alarm-logger.nix b/nixos/modules/phoebus/alarm-logger.nix index 1d24f62e..b61bfe35 100644 --- a/nixos/modules/phoebus/alarm-logger.nix +++ b/nixos/modules/phoebus/alarm-logger.nix @@ -11,17 +11,17 @@ in { options.services.phoebus-alarm-logger = { enable = lib.mkEnableOption '' - the Phoebus Alarm logger + the Phoebus Alarm logger. The alarm logging service records all alarm messages to create an archive - of all alarm state changes and the associated actions. - ''; + of all alarm state changes and the associated actions''; openFirewall = lib.mkOption { description = '' Open the firewall for the Phoebus Alarm Logger service. - Warning: this opens the firewall on all network interfaces. + .. warning:: + This opens the firewall on all network interfaces. ''; type = lib.types.bool; default = false; @@ -31,12 +31,12 @@ in { description = '' Configuration for the Phoebus Alarm Logger. - These options will be put into a `.properties` file. + These options will be put into a ``.properties`` file. Note that options containing a "." must be quoted. Available options can be seen here: - + https://github.com/ControlSystemStudio/phoebus/blob/master/services/alarm-logger/src/main/resources/application.properties ''; default = {}; type = lib.types.submodule { @@ -93,7 +93,7 @@ in { description = '' Units of the indices date span. - Can be Days (D), Weeks(W), Months(M), Years(Y) + Can be Days (D), Weeks (W), Months (M), Years (Y). ''; type = lib.types.enum ["D" "W" "M" "Y"]; default = "M"; diff --git a/nixos/modules/phoebus/alarm-server.nix b/nixos/modules/phoebus/alarm-server.nix index 736fc0b2..cfbbca5b 100644 --- a/nixos/modules/phoebus/alarm-server.nix +++ b/nixos/modules/phoebus/alarm-server.nix @@ -15,7 +15,7 @@ in { the Phoebus Alarm server By default this option will also enable the phoebus-alarm-logger service. - Set `services.phoebus-alarm-logger.enable = false;` to disable it. + Set :nix:option:`services.phoebus-alarm-logger.enable` to ``false`` to disable it. ''; # TODO: why undocumented? Seems useful @@ -31,11 +31,12 @@ in { This uses the port numbers configured in each related NixOS module. - Includes services: + Included services: - Phoebus Alarm Logger (if not disabled) - Warning: this opens the firewall on all network interfaces. + .. warning:: + This opens the firewall on all network interfaces. ''; type = lib.types.bool; default = false; @@ -45,7 +46,7 @@ in { description = '' Configuration for the Phoebus Alarm Server. - These options will be put into a `.properties` file. + These options will be put into a ``.properties`` file. Note that options containing a "." must be quoted. ''; @@ -105,7 +106,7 @@ in { description = '' The SMTP server host. - If set to DISABLE (the default), email support is disabled. + If set to ``"DISABLE"`` (the default), email support is disabled. ''; type = lib.types.str; default = "DISABLE"; @@ -132,7 +133,9 @@ in { description = '' Password for authenticating to the SMTP server. - Note: the password will be put in plaintext, in the world-readable `/nix/store`. + .. note:: + The password will be put in plaintext, + in the world-readable ``/nix/store``. ''; type = lib.types.str; default = ""; @@ -140,7 +143,7 @@ in { "org.phoebus.email/from" = lib.mkOption { description = '' - Default address to be used for the email field `From:`. + Default address to be used for the email field :mailheader:`From`. If left empty, then the last used from address is used. ''; diff --git a/nixos/modules/phoebus/olog.nix b/nixos/modules/phoebus/olog.nix index 0ac3a078..df9e2bda 100644 --- a/nixos/modules/phoebus/olog.nix +++ b/nixos/modules/phoebus/olog.nix @@ -16,12 +16,12 @@ in { description = '' Configuration for the Phoebus Olog service. - These options will be put into a `.properties` file. + These options will be put into a ``.properties`` file. Note that options containing a "." must be quoted. See here for supported options: - + https://github.com/Olog/phoebus-olog/blob/v${pkgs.epnix.phoebus-olog.version}/src/main/resources/application.properties ''; default = {}; type = lib.types.submodule { @@ -34,14 +34,14 @@ in { # It says it supports integers and booleans, but during the build # only accepts strings? apply = toString; - description = "The server port for the REST service"; + description = "The server port for the REST service."; }; "server.http.enable" = lib.mkOption { type = lib.types.bool; default = false; apply = lib.boolToString; - description = "Enable unsecure HTTP"; + description = "Enable unsecure HTTP."; }; "demo_auth.enabled" = lib.mkOption { @@ -53,8 +53,8 @@ in { Phoebus will provide two users: - - `admin:adminPass` - - `user:userPass` + - ``admin:adminPass`` + - ``user:userPass`` ''; }; diff --git a/nixos/modules/phoebus/save-and-restore.nix b/nixos/modules/phoebus/save-and-restore.nix index 60004872..139109ff 100644 --- a/nixos/modules/phoebus/save-and-restore.nix +++ b/nixos/modules/phoebus/save-and-restore.nix @@ -16,14 +16,14 @@ in { This service is used by clients to manage configurations (aka save sets) and snapshots, to compare snapshots, - and to restore PV values from snapshots. - ''; + and to restore PV values from snapshots''; openFirewall = lib.mkOption { description = '' Open the firewall for the Phoebus Save-and-restore service. - Warning: this opens the firewall on all network interfaces. + .. warning:: + This opens the firewall on all network interfaces. ''; type = lib.types.bool; default = false; @@ -33,12 +33,12 @@ in { description = '' Configuration for the Phoebus Save-and-restore service. - These options will be put into a `.properties` file. + These options will be put into a ``.properties`` file. Note that options containing a "." must be quoted. Available options can be seen here: - + https://github.com/ControlSystemStudio/phoebus/blob/master/services/save-and-restore/src/main/resources/application.properties ''; default = {}; type = lib.types.submodule { @@ -53,9 +53,9 @@ in { "elasticsearch.network.host" = lib.mkOption { description = '' - Elasticsearch server host + Elasticsearch server host. - If `localhost` (the default), + If ``localhost`` (the default), the Elasticsearch service will be automatically set up. ''; type = lib.types.str; @@ -63,7 +63,7 @@ in { }; "elasticsearch.http.port" = lib.mkOption { - description = "Elasticsearch server port"; + description = "Elasticsearch server port."; type = lib.types.port; default = config.services.elasticsearch.port; defaultText = lib.literalExpression "config.services.elasticsearch.port"; diff --git a/pkgs/default.nix b/pkgs/default.nix index 9fcee2c1..295b3041 100644 --- a/pkgs/default.nix +++ b/pkgs/default.nix @@ -1,4 +1,4 @@ -epnixLib: final: prev: let +epnixLib: inputs: final: prev: let inherit (final) callPackage; # From prev, else it somehow causes an infinite recursion inherit (prev) recurseIntoAttrs; @@ -100,7 +100,9 @@ in open62541_1_3 = callPackage ./epnix/tools/open62541_1_3 {}; # EPNix specific packages - docs = callPackage ./docs {}; + docs = callPackage ./docs { + nixdomainLib = inputs.sphinxcontrib-nixdomain.lib; + }; # Documentation support packages psu-simulator = callPackage ./doc-support/psu-simulator {}; diff --git a/pkgs/docs/default.nix b/pkgs/docs/default.nix index 38c371b1..d1d16ee6 100644 --- a/pkgs/docs/default.nix +++ b/pkgs/docs/default.nix @@ -6,6 +6,7 @@ writeText, python3, installShellFiles, + nixdomainLib, documentedEpnixPkgs ? epnix, iocConfig ? {}, nixosConfig ? {}, @@ -15,6 +16,35 @@ iocOptions = documentation.options.iocOptions iocConfig; nixosOptions = documentation.options.nixosOptions nixosConfig; + nixosOptionsAttrSet = (epnixLib.inputs.nixpkgs.lib.nixosSystem { + inherit (stdenvNoCC) system; + modules = [ + epnixLib.inputs.self.nixosModules.nixos + ]; + }).options; + + isOurs = option: lib.any (lib.hasPrefix "${epnixLib.inputs.self}") option.declarations; + isVisible = option: !option.internal; + + relativePath = path: lib.pipe path [ + (lib.splitString "/") + (lib.sublist 4 255) + (lib.concatStringsSep "/") + ]; + + # rev = epnixLib.inputs.self.sourceInfo.rev or "master"; + + nixosOptionsSpec = lib.pipe nixosOptionsAttrSet [ + nixdomainLib.optionAttrSetToDocList + (lib.filter isOurs) + (lib.filter isVisible) + (map (x: x // { declarations = map relativePath x.declarations; })) + (map (x: lib.nameValuePair x.name x)) + lib.listToAttrs + builtins.toJSON + (writeText "nixos-options.json") + ]; + iocOptionsContent = documentation.options.optionsContent iocOptions 3; # Have a separate "Options" header for the Sphinx manpage output iocOptionsPandoc = '' @@ -27,17 +57,6 @@ ${iocOptionsContent} ''; - nixosOptionsContent = documentation.options.optionsContent nixosOptions 3; - nixosOptionsPandoc = '' - NixOS options reference - ======================= - - Options - ------- - - ${nixosOptionsContent} - ''; - iocPkgsListPandoc = '' IOC packages list ================= @@ -80,6 +99,7 @@ in myst-parser sphinx sphinx-copybutton + sphinxcontrib-nixdomain ]) ++ [ installShellFiles @@ -91,10 +111,20 @@ in mkdir ioc/references mkdir pkgs - cp "${writeText "ioc-options.md" iocOptionsPandoc}" ioc/references/options.md - cp "${writeText "ioc-packages.md" iocPkgsListPandoc}" ioc/references/packages.md - cp "${writeText "nixos-options.md" nixosOptionsPandoc}" nixos-services/options.md - cp "${writeText "packages.md" pkgsListPandoc}" pkgs/packages.md + cp -v "${nixosOptionsSpec}" nixos-options.json + cp -v "${writeText "ioc-options.md" iocOptionsPandoc}" ioc/references/options.md + cp -v "${writeText "ioc-packages.md" iocPkgsListPandoc}" ioc/references/packages.md + cp -v "${writeText "packages.md" pkgsListPandoc}" pkgs/packages.md + ''; + + shellHook = '' + if [[ -f docs/index.rst ]]; then + install -v "${nixosOptionsSpec}" docs/nixos-options.json + elif [[ -f index.rst ]]; then + install -v "${nixosOptionsSpec}" nixos-options.json + else + echo "Couldn't find root of docs directory, not copying options.json files" + fi ''; buildPhase = ''