docs: switch to sphinxcontrib-nixdomain for NixOS options

epics-extensions · Nov 4, 2024 · 063d5b1 · 063d5b1
1 parent 2386155
commit 063d5b1
Show file tree

Hide file tree

Showing 28 changed files with 320 additions and 126 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +1,2 @@
 _build
+*-options.json
diff --git 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": """
                 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
                     <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <opt-services.archiver-appliance.stores.sts.size>` 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
@@ -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
@@ -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
diff --git 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
@@ -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;