Merge pull request #132 from minijackson/mrf-doc

MRF documentation

docs/ioc/user-guides/index.rst

@@ -13,6 +13,7 @@ User guides
    ./private-repo-setup.rst
    ./flake-registry.rst
    ./developing-modules.rst
+   ./mrf-devices.rst
    ./testing/packaging-python-scripts.rst
 
 .. TODO: make a NixOS test user-guide,

docs/ioc/user-guides/mrf-devices.rst

@@ -0,0 +1,46 @@
+Micro Research Finland timing devices
+=====================================
+
+To control Micro Research Finland (MRF) devices,
+we recommend using the :ref:`pkg-support.mrfioc2` EPICS module.
+
+Installing the ``mrfioc2`` EPICS support module
+-----------------------------------------------
+
+To use the ``mrfioc2`` module in your EPNix IOC,
+make sure to add the :ref:`pkg-support.mrfioc2` package in your support modules:
+
+.. code-block:: diff
+   :caption: :file:`flake.nix`
+
+            # Add your support modules here:
+            # ---
+   -        #support.modules = with pkgs.epnix.support; [ StreamDevice mySupportModule ];
+   +        support.modules = with pkgs.epnix.support; [ mrfioc2 ];
+
+This makes sure that the ``mrfioc2`` is available during compilation.
+
+For developing your IOC using ``mrfioc2``,
+follow the `mrfioc2 documentation`_.
+
+.. _mrfioc2 documentation: https://epics-modules.github.io/mrfioc2/
+
+Installing the ``mrf`` kernel module
+------------------------------------
+
+To communicate with the MRF devices,
+you also need to install and load the ``mrf`` kernel module.
+
+If you are using NixOS,
+add this to the NixOS configuration of the board running the IOC:
+
+.. code-block:: nix
+   :caption: :file:`mrf.nix`
+
+   { config, ... }:
+   {
+     # Install the MRF kernel module package
+     boot.extraModulePackages = with config.boot.kernelPackages; [ mrf ];
+     # Load the "mrf" module at boot
+     boot.kernelModules = [ "mrf" ];
+   }

lib/documentation.nix

@@ -6,7 +6,7 @@
     isVisible = pkg: !(pkg.value.meta.hidden or false);
 
     isNotIocSpecific = base: pkg: (self.isVisible pkg) && base != "support.";
-    isIocSpecific = base: pkg: (self.isVisible pkg) && (pkg.value.pname == "epics-base" || base == "support.");
+    isIocSpecific = base: pkg: (self.isVisible pkg) && base == "support.";
 
     filteredPkgsList = filt: headingLevel: pkgs:
       lib.concatStringsSep
@@ -79,6 +79,7 @@
     package2pandoc = headingLevel: path: pkg: let
       header = lib.fixedWidthString headingLevel "#" "";
     in ''
+      (pkg-${path})=
       ${header} ${pkg.pname or pkg.name}
 
       Path

lib/documentation/markdown.nix

@@ -12,8 +12,6 @@ lib.fix (self: let
     then ''"${el}"''
     else el;
 
-  # Add a suggested word break after each "." so that it is easier to read
-  wordBreakOption = loc: lib.concatStringsSep ".<wbr>" (map maybeQuote loc);
   optionName = loc: lib.concatStringsSep "." (map maybeQuote loc);
 
   isLiteral = value:

pkgs/epnix/support/mrfioc2/default.nix

@@ -31,7 +31,7 @@ mkEpicsPackage rec {
   '';
 
   meta = {
-    description = "Driver EPICS for MRF cards";
+    description = "EPICS driver for Micro Research Finland event timing system devices";
     homepage = "https://github.com/epics-modules/mrfioc2";
     license = epnixLib.licenses.epics;
     maintainers = with epnixLib.maintainers; [agaget];