Fix docs (#75) (#76)

* Add compat for Documenter

* Update client.md

* Update installation.md

* Update generation.md

* Update acquisition.md

* Update scpi.md

* Update Acquisition.jl

* Update ADC.jl

* Update Acquisition.jl

* Turn missing docs to warnings

* WIP

docs/Project.toml

@@ -1,2 +1,5 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -27,7 +27,8 @@ makedocs(
         "FPGA Development" => "fpga.md",
         "Development Tips" => "devtips.md",
         #"Getting Started" => "overview.md",
-    ]
+    ],
+    warnonly = [:missing_docs]
 #    html_prettyurls = false, #!("local" in ARGS),
 )
 

docs/src/acquisition.md

@@ -1,6 +1,6 @@
-# Data Acqusition
+# Data Acquisition
 
-The data acqusition of the RedPitayaDAQServer project is based on two data flows to and from the upper 128 MB of the RedPitaya memory. This memory region acts as a ring buffer for the acquired samples and can be queried by clients using SCPI commands.
+The data acquisition of the RedPitayaDAQServer project is based on two data flows to and from the upper 128 MB of the RedPitaya memory. This memory region acts as a ring buffer for the acquired samples and can be queried by clients using SCPI commands.
 
 Signal acquisition within a cluster is based on a shared clock and trigger signal distributed via cables between the RedPitayas. Once triggered, all FPGAs continuously write the samples from their ADC channel to the sample ring-buffer with each clock tick. Both ADC channels on a RedPitaya are written to the buffer at the same time. The 14-bit values of the ADCs are converted to 16-bit signed integer samples and then concatenated into one 32-bit value, which is then written to the buffer. The sampling rate of the system can be adjusted by setting a decimation parameter and the decimation itself is realized with a CIC filter.
 
@@ -43,4 +43,4 @@ At this sampling rate a single RedPitaya produces new samples at a data rate of
 |16|7.81|31.25|250|4.29s|
 |8|15.63|62.5|500|2.15s|
 
-The table only refers to the data rate of new samples being produced. The data rate of samples being transmitted to a client can differ greatly depending on how the client queries and processes the samples and the available network bandwidth and usage. At the higher sampling rates it is recommended to have client threads that exclusively receive samples and perform any computation on samples in different threads to maximise the transmission speed, as a server can only transmit data at a rate of just above 500 Mbit/s. This exceeds the highest supported sampling rate by only a few Mbit/s and a client with frequency interruptions of its sample reception might not be able to keep up with the sampling rate.
+The table only refers to the data rate of new samples being produced. The data rate of samples being transmitted to a client can differ greatly depending on how the client queries and processes the samples and the available network bandwidth and usage. At the higher sampling rates it is recommended to have client threads that exclusively receive samples and perform any computation on samples in different threads to maximise the transmission speed, as a server can only transmit data at a rate of just above 500 Mbit/s. This exceeds the highest supported sampling rate by only a few Mbit/s and a client with frequency interruptions of its sample reception might not be able to keep up with the sampling rate.

docs/src/client.md

@@ -2,6 +2,7 @@
 This page contains documentation of the public API of the Julia client. In the Julia
 REPL one can access this documentation by entering the help mode with `?` and
 then writing the function for which the documentation should be shown.
+
 ## Connection and Communication
 ```@docs
 RedPitayaDAQServer.RedPitaya
@@ -40,6 +41,7 @@ RedPitayaDAQServer.calibADCOffset
 RedPitayaDAQServer.calibADCOffset!
 RedPitayaDAQServer.calibADCScale
 RedPitayaDAQServer.calibADCScale!
+RedPitayaDAQServer.updateCalib!
 ```
 ## DAC Configuration
 ```@docs
@@ -61,12 +63,12 @@ RedPitayaDAQServer.samplesPerStep!
 RedPitayaDAQServer.stepsPerFrame!
 RedPitayaDAQServer.clearSequence!
 RedPitayaDAQServer.sequence!
-RedPitayaDAQServer.length(::AbstractSequence)
-RedPitayaDAQServer.start
 RedPitayaDAQServer.calibDACOffset
 RedPitayaDAQServer.calibDACOffset!
 RedPitayaDAQServer.calibDACScale
 RedPitayaDAQServer.calibDACScale!
+RedPitayaDAQServer.calibDACUpperLimit!
+RedPitayaDAQServer.calibDACLowerLimit!
 ```
 ## Measurement and Transmission
 ```@docs
@@ -79,11 +81,22 @@ RedPitayaDAQServer.SampleChunk
 RedPitayaDAQServer.PerformanceData
 RedPitayaDAQServer.readSamples
 RedPitayaDAQServer.readFrames
-RedPitayaDAQServer.convertSamplesToFrames
+RedPitayaDAQServer.readPeriods
+RedPitayaDAQServer.convertSamplesToFrames(::Union{RedPitaya, RedPitayaCluster, RedPitayaClusterView}, ::Any, ::Any, ::Any, ::Any, ::Any, ::Any, ::Any)
+RedPitayaDAQServer.convertSamplesToPeriods!(::Union{RedPitaya, RedPitayaCluster, RedPitayaClusterView}, ::Any, ::Any, ::Any, ::Any, ::Any, ::Any)
+```
+## Slow IO
+```@autodocs
+Modules = [RedPitayaDAQServer]
+Pages   = ["SlowIO.jl"]
+```
+## EEPROM and Calibration
+```@autodocs
+Modules = [RedPitayaDAQServer]
+Pages   = ["EEPROM.jl"]
+```
+## Counter Trigger
+```@autodocs
+Modules = [RedPitayaDAQServer]
+Pages   = ["CounterTrigger.jl"]
 ```
-## Utility
-```@docs
-RedPitayaDAQServer.listReleaseTags
-RedPitayaDAQServer.latestReleaseTags
-RedPitayaDAQServer.update!
-```

docs/src/generation.md

@@ -28,9 +28,9 @@ Comparable to the sample transmission of the acquisition, this updating of the L
 Sequences and their steps also have additional features. A step can be marked such that during its duration the signal is set to 0. Furthermore, a step can be marked such that it triggers the ramp down. To make this easier to manage the server actually manages three sequences, that can be set individually: A ramp up, regular and ramp down sequence. The ramp up sequence is moved to the FPGA LUT at the acquisition start, followed by the regular sequence. Afterwards the ramp down sequence is started and during its execution the ramp down flag is set.
 
 ## Calibration
-Similar to the signal acqusition, there are also calibration scale ``c_{i, scale}`` and offset ``c_{i, offset}`` values  for the signal generation. These are stored in the EEPROM of the RedPitaya and can be updated by a client. The calibration values are always applied, even when the master trigger is off.
+Similar to the signal acquisition, there are also calibration scale ``c_{i, scale}`` and offset ``c_{i, offset}`` values  for the signal generation. These are stored in the EEPROM of the RedPitaya and can be updated by a client. The calibration values are always applied, even when the master trigger is off.
 
 Thus the total signal can be described as:
 ```math
 S_i''(t) = c_{i, scale} S_i'(t) + c_{i, offset}
-```
+```

docs/src/installation.md

@@ -15,7 +15,7 @@ To finish installing the RedPitaya, simply unzip one of the releases and copy th
 
 When the RedPitaya is now booted, the server should start. One can then use a client to connect, at which point the FPGA image is loaded. 
 
-The client library provided with the project is not an executable program, but it can be used to implement one. The library encapsulates the communication with the server and implements various optimizations. As the communication with the server is language agnostic one could therefore implement their own client in a different language. The Julia reference client library found in `src/client/julia`, the [SCPI commands](scpi.md) and the sections on the signal [acquisition](acqusition.md) and [generation](generation.md) are starting points for such a custom client.
+The client library provided with the project is not an executable program, but it can be used to implement one. The library encapsulates the communication with the server and implements various optimizations. As the communication with the server is language agnostic one could therefore implement their own client in a different language. The Julia reference client library found in `src/client/julia`, the [SCPI commands](scpi.md) and the sections on the signal [acquisition](acquisition.md) and [generation](generation.md) are starting points for such a custom client.
 
 ## Julia Client
 To use the provided Julia client library you need to install RedPitayaDAQServer Julia package within Julia. To this end 
@@ -148,4 +148,4 @@ dev RedPitayaDAQServer
 ```
 in the package mode `]`.
 
-This installs the package in development mode and puts the files into `~/.julia/dev/RedPitayaDAQServer/`. There you can the also modify the files, which is handy when trying out the examples. You need to manually `git pull` if you want to get updates, i.e. Julia will not update developed packages automatically.
+This installs the package in development mode and puts the files into `~/.julia/dev/RedPitayaDAQServer/`. There you can the also modify the files, which is handy when trying out the examples. You need to manually `git pull` if you want to get updates, i.e. Julia will not update developed packages automatically.

docs/src/scpi.md

@@ -39,7 +39,7 @@ After each SCPI command the server replies with `true` or `false` on the command
 
 
 ## Sequence Configuration
-The server maintains three acqusition sequences. When the server is in the`CONFIGURATION` mode a client can configure a set of three sequences. If the current configured sequences fits the desired signal, a client can intstruct the server to set the sequences. This moves the configuration sequences to the acquisition sequences and writes the first values to the FPGA buffer.
+The server maintains three acquisition sequences. When the server is in the`CONFIGURATION` mode a client can configure a set of three sequences. If the current configured sequences fits the desired signal, a client can intstruct the server to set the sequences. This moves the configuration sequences to the acquisition sequences and writes the first values to the FPGA buffer.
 
 During an active trigger the buffer is periodically updated by the server. If the server recognizes the end of a sequence, it sets the amplitudes of the waveform components to 0.
 

src/client/julia/src/ADC.jl

@@ -29,7 +29,11 @@ end
 
 RPStatus(statusRaw::Integer) = RPStatus((statusRaw >> 0) & 1, (statusRaw >> 1) & 1, (statusRaw >> 2) & 1, (statusRaw >> 3) & 1, (statusRaw >> 4) & 1)
 
+"""
+    PerformanceData
 
+Holds the performance data that is used for monitoring.
+"""
 struct PerformanceData
   wpRead::UInt64
   adc::ADCPerformanceData

src/client/julia/src/Acquisition.jl

@@ -209,6 +209,13 @@ function readFrames(rpu::Union{RedPitaya,RedPitayaCluster, RedPitayaClusterView}
   return data
 end
 
+"""
+    convertSamplesToFrames(rpu::Union{RedPitayaCluster, RedPitayaClusterView}, samples, numChan, numSampPerPeriod, numPeriods, numFrames, numBlockAverages=1, numPeriodsPerPatch=1)
+
+Converts a given set of samples to frames.
+
+See [`readFrames`](@ref)
+"""
 function convertSamplesToFrames(rpu::Union{RedPitaya, RedPitayaCluster, RedPitayaClusterView}, samples, numChan, numSampPerPeriod, numPeriods, numFrames, numBlockAverages=1, numPeriodsPerPatch=1)
   frames = convertSamplesToFrames(samples, numChan, numSampPerPeriod, numPeriods, numFrames, numBlockAverages, numPeriodsPerPatch)
   calibs = [x.calib for x in rpu]
@@ -220,6 +227,13 @@ function convertSamplesToFrames(rpu::Union{RedPitaya, RedPitayaCluster, RedPitay
   return frames
 end
 
+"""
+    convertSamplesToFrames(samples, numChan, numSampPerPeriod, numPeriods, numFrames, numBlockAverages=1, numPeriodsPerPatch=1)
+
+Converts a given set of samples to frames.
+
+See [`readFrames`](@ref)
+"""
 function convertSamplesToFrames(samples, numChan, numSampPerPeriod, numPeriods, numFrames, numBlockAverages=1, numPeriodsPerPatch=1)
   if rem(numSampPerPeriod,numBlockAverages) != 0
     error("block averages has to be a divider of numSampPerPeriod")
@@ -230,6 +244,13 @@ function convertSamplesToFrames(samples, numChan, numSampPerPeriod, numPeriods,
   return frames
 end
 
+"""
+    convertSamplesToFrames!(rpu::Union{RedPitayaCluster, RedPitayaClusterView}, samples, frames, numChan, numSampPerPeriod, numPeriods, numFrames, numTrueSampPerPeriod, numBlockAverages=1, numPeriodsPerPatch=1)
+
+Converts a given set of samples to frames in-place.
+
+See [`readFrames`](@ref)
+"""
 function convertSamplesToFrames!(rpu::Union{RedPitaya, RedPitayaCluster, RedPitayaClusterView}, samples, frames, numChan, numSampPerPeriod, numPeriods, numFrames, numTrueSampPerPeriod, numBlockAverages=1, numPeriodsPerPatch=1)
   convertSamplesToFrames!(samples, frames, numChan, numSampPerPeriod, numPeriods, numFrames, numTrueSampPerPeriod, numBlockAverages, numPeriodsPerPatch)
   calibs = [x.calib for x in rpu]
@@ -240,6 +261,13 @@ function convertSamplesToFrames!(rpu::Union{RedPitaya, RedPitayaCluster, RedPita
   end
 end
 
+"""
+    convertSamplesToFrames!(samples, frames, numChan, numSampPerPeriod, numPeriods, numFrames, numTrueSampPerPeriod, numBlockAverages=1, numPeriodsPerPatch=1)
+
+Converts a given set of samples to frames in-place.
+
+See [`readFrames`](@ref)
+"""
 function convertSamplesToFrames!(samples, frames, numChan, numSampPerPeriod, numPeriods, numFrames, numTrueSampPerPeriod, numBlockAverages=1, numPeriodsPerPatch=1)
   temp = reshape(samples, numChan, numSampPerPeriod, numPeriods, numFrames)
   for d = 1:div(numChan,2)
@@ -292,6 +320,13 @@ function readPeriods(rpu::Union{RedPitaya,RedPitayaCluster, RedPitayaClusterView
   return data
 end
 
+"""
+    convertSamplesToPeriods!(rpu::Union{RedPitaya, RedPitayaCluster, RedPitayaClusterView}, samples, periods, numChan, numSampPerPeriod, numPeriods, numBlockAverages=1)
+
+Converts a given set of samples to periods in-place.
+
+See [`readPeriods`](@ref)
+"""
 function convertSamplesToPeriods!(rpu::Union{RedPitaya, RedPitayaCluster, RedPitayaClusterView}, samples, periods, numChan, numSampPerPeriod, numPeriods, numBlockAverages=1)
   convertSamplesToPeriods!(samples, periods, numChan, numSampPerPeriod, numPeriods, numBlockAverages)
   calibs = [x.calib for x in rpu]
@@ -303,6 +338,14 @@ function convertSamplesToPeriods!(rpu::Union{RedPitaya, RedPitayaCluster, RedPit
   return periods
 
 end
+
+"""
+    convertSamplesToPeriods!(samples, periods, numChan, numSampPerPeriod, numPeriods, numBlockAverages=1)
+
+Converts a given set of samples to periods in-place.
+
+See [`readPeriods`](@ref)
+"""
 function convertSamplesToPeriods!(samples, periods, numChan, numSampPerPeriod, numPeriods, numBlockAverages=1)
   temp = reshape(samples, numChan, numSampPerPeriod, numPeriods)
   for d = 1:div(numChan,2)
@@ -312,4 +355,4 @@ function convertSamplesToPeriods!(samples, periods, numChan, numSampPerPeriod, n
     periods[:,2*d-1,:] = utmp2[1,:,1,:]
     periods[:,2*d,:] = utmp2[2,:,1,:]
   end
-end
+end

src/client/julia/src/EEPROM.jl

@@ -14,6 +14,7 @@ function calibDACOffset!(rp::RedPitaya, channel::Integer, val)
 end
 scpiCommand(::typeof(calibDACOffset!), channel::Integer, val) = string("RP:CALib:DAC:CH", Int(channel) - 1, ":OFF $(Float32(val))")
 scpiReturn(::typeof(calibDACOffset!)) = Bool
+
 """
     calibDACOffset(rp::RedPitaya, channel::Integer)
 
@@ -34,6 +35,7 @@ function calibDACScale!(rp::RedPitaya, channel::Integer, val)
 end
 scpiCommand(::typeof(calibDACScale!), channel::Integer, val) = string("RP:CALib:DAC:CH", Int(channel) - 1, ":SCA $(Float32(val))")
 scpiReturn(::typeof(calibDACScale!)) = Bool
+
 """
     calibDACScale(rp::RedPitaya, channel::Integer)
 
@@ -54,6 +56,7 @@ function calibDACLowerLimit!(rp::RedPitaya, channel::Integer, val)
 end
 scpiCommand(::typeof(calibDACLowerLimit!), channel::Integer, val) = string("RP:CALib:DAC:CH", Int(channel) - 1, ":LIM:LOW $(Float32(val))")
 scpiReturn(::typeof(calibDACLowerLimit!)) = Bool
+
 """
     calibDACLowerLimit(rp::RedPitaya, channel::Integer)
 
@@ -74,6 +77,7 @@ function calibDACUpperLimit!(rp::RedPitaya, channel::Integer, val)
 end
 scpiCommand(::typeof(calibDACUpperLimit!), channel::Integer, val) = string("RP:CALib:DAC:CH", Int(channel) - 1, ":LIM:UP $(Float32(val))")
 scpiReturn(::typeof(calibDACUpperLimit!)) = Bool
+
 """
     calibDACUpperLimit(rp::RedPitaya, channel::Integer)
 
@@ -103,7 +107,7 @@ end
 Store calibration ADC offset `val` for given channel into the RedPitayas EEPROM.
 Absolute value has to be smaller than 1.0 V.
 
-See also [convertSamplesToPeriods](@ref),[convertSamplesToFrames](@ref).
+See also [convertSamplesToPeriods!](@ref),[convertSamplesToFrames](@ref).
 """
 function calibADCOffset!(rp::RedPitaya, channel::Integer, val)
   if abs(val) > 1.0
@@ -114,12 +118,13 @@ function calibADCOffset!(rp::RedPitaya, channel::Integer, val)
 end
 scpiCommand(::typeof(calibADCOffset!), channel::Integer, val) = string("RP:CALib:ADC:CH", Int(channel) - 1, ":OFF $(Float32(val))")
 scpiReturn(::typeof(calibADCOffset!)) = Bool
+
 """
     calibADCOffset(rp::RedPitaya, channel::Integer)
 
 Retrieve the calibration ADC offset for given channel from the RedPitayas EEPROM.
 
-See also [convertSamplesToPeriods](@ref),[convertSamplesToFrames](@ref).
+See also [convertSamplesToPeriods!](@ref),[convertSamplesToFrames](@ref).
 """
 calibADCOffset(rp::RedPitaya, channel::Integer) = query(rp, scpiCommand(calibADCOffset, channel), scpiReturn(calibADCOffset))
 scpiCommand(::typeof(calibADCOffset), channel::Integer) = string("RP:CALib:ADC:CH", Int(channel) - 1, ":OFF?")
@@ -129,20 +134,21 @@ scpiReturn(::typeof(calibADCOffset)) = Float64
     calibADCScale(rp::RedPitaya, channel::Integer)
 
 Store calibration ADC scale `val` for given channel into the RedPitayas EEPROM.
-See also [convertSamplesToPeriods](@ref),[convertSamplesToFrames](@ref).
+See also [convertSamplesToPeriods!](@ref),[convertSamplesToFrames](@ref).
 """
 function calibADCScale!(rp::RedPitaya, channel::Integer, val)
   rp.calib[1, channel] = Float32(val)
   return query(rp, scpiCommand(calibADCScale!, channel::Integer, val), scpiReturn(calibADCScale!))
 end
 scpiCommand(::typeof(calibADCScale!), channel, val) = string("RP:CALib:ADC:CH", Int(channel) - 1, ":SCA $(Float32(val))")
 scpiReturn(::typeof(calibADCScale!)) = Bool
+
 """
     calibADCScale(rp::RedPitaya, channel::Integer)
 
 Retrieve the calibration ADC scale for given channel from the RedPitayas EEPROM.
 
-See also [convertSamplesToPeriods](@ref),[convertSamplesToFrames](@ref).
+See also [convertSamplesToPeriods!](@ref),[convertSamplesToFrames](@ref).
 """
 calibADCScale(rp::RedPitaya, channel::Integer) = query(rp, scpiCommand(calibADCScale, channel), scpiReturn(calibADCScale))
 scpiCommand(::typeof(calibADCScale), channel::Integer) = string("RP:CALib:ADC:CH", Int(channel) - 1, ":SCA?")
@@ -152,6 +158,13 @@ calibFlags(rp::RedPitaya) = query(rp, scpiCommand(calibFlags), scpiReturn(calibF
 scpiCommand(::typeof(calibFlags)) = "RP:CALib:FLAGs"
 scpiReturn(::typeof(calibFlags)) = Int64
 
+"""
+    updateCalib!(rp::RedPitaya)
+
+Update the cached calibration values.
+
+See also [calibADCScale](@ref), [calibADCOffset](@ref).
+"""
 function updateCalib!(rp::RedPitaya)
   rp.calib[1, 1] = calibADCScale(rp, 1)
   rp.calib[2, 1] = calibADCOffset(rp, 1)

src/client/julia/src/RedPitayaDAQServer.jl

@@ -76,6 +76,11 @@ function receive(rp::RedPitaya)
   return readline(rp.socket)[1:end]
 end
 
+"""
+    receive(rp::RedPitaya, ch::Channel)
+
+Receive a String from the RedPitaya command socket. Reads until a whole line is received and puts it in the supplied channel `ch`.
+"""
 function receive(rp::RedPitaya, ch::Channel)
   put!(ch, receive(rp))
 end