addition of docstrings

.github/workflows/CI.yml

@@ -86,4 +86,20 @@ jobs:
           fail_ci_if_error: true
           token: ${{ secrets.CODECOV_TOKEN }}
           files: lcov.info
-          args: '--exclude ext/*'
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # Needed due to https://github.com/JuliaDocs/Documenter.jl/issues/1177
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          GKSwstype: 'nul'

docs/src/api.md

@@ -8,9 +8,49 @@ Order = [:macro, :function]
 ```
 
 ## Documentation
+
+### analysis.jl
 ```@docs
+ZeroNuFit.Analysis.retrieve_real_fit_results
+ZeroNuFit.Analysis.run_analysis
 ZeroNuFit.Analysis.save_outputs
+```
+
+### likelihood.jl
+```@docs
+ZeroNuFit.Likelihood.norm_uniform
+ZeroNuFit.Likelihood.norm_linear
+ZeroNuFit.Likelihood.norm_exponential
+ZeroNuFit.Likelihood.exp_stable
+ZeroNuFit.Likelihood.gaussian_plus_lowEtail
+ZeroNuFit.Likelihood.get_mu_b
+ZeroNuFit.Likelihood.get_mu_s
+ZeroNuFit.Likelihood.get_mu_s_b
+ZeroNuFit.Likelihood.build_likelihood_zero_obs_evts
+ZeroNuFit.Likelihood.build_likelihood_per_partition
+ZeroNuFit.Likelihood.build_likelihood_looping_partitions
+ZeroNuFit.Likelihood.get_stat_blocks
+ZeroNuFit.Likelihood.run_fit_over_partitions
+ZeroNuFit.Likelihood.get_signal_prior_info
+ZeroNuFit.Likelihood.get_signal_bkg_priors
+ZeroNuFit.Likelihood.get_bkg_pdf
+ZeroNuFit.Likelihood.get_signal_pdf
+ZeroNuFit.Likelihood.build_prior
+ZeroNuFit.Likelihood.generate_data
+```
+
+### plotting.jl
+```@docs
+ZeroNuFit.Plotting.plot_data
+ZeroNuFit.Plotting.plot_fit_and_data
+ZeroNuFit.Plotting.plot_correlation_matrix
+ZeroNuFit.Plotting.plot_marginal_distr
+ZeroNuFit.Plotting.plot_two_dim_posteriors
+ZeroNuFit.Plotting.fit_model
+```
 
+### utils.jl
+```@docs
 ZeroNuFit.Utils.check_key
 ZeroNuFit.Utils.get_settings
 ZeroNuFit.Utils.get_events
@@ -25,29 +65,11 @@ ZeroNuFit.Utils.get_efficiency
 ZeroNuFit.Utils.get_deltaE
 ZeroNuFit.Utils.get_range
 ZeroNuFit.Utils.get_bkg_info
-ZeroNuFit.Utils.save_generated_samples
-ZeroNuFit.Utils.save_results_into_json
 ZeroNuFit.Utils.get_global_mode
 ZeroNuFit.Utils.get_marginalized_mode
-
-ZeroNuFit.Plotting.plot_data
-ZeroNuFit.Plotting.plot_correlation_matrix
-ZeroNuFit.Plotting.plot_marginal_distr
-
-ZeroNuFit.Likelihood.get_stat_blocks
-ZeroNuFit.Likelihood.run_fit_over_partitions
-ZeroNuFit.Likelihood.get_signal_prior_info
-ZeroNuFit.Likelihood.norm_uniform
-ZeroNuFit.Likelihood.norm_linear
-ZeroNuFit.Likelihood.norm_exponential
-ZeroNuFit.Likelihood.gaussian_plus_lowEtail
-ZeroNuFit.Likelihood.get_mu_b
-ZeroNuFit.Likelihood.get_mu_s
-ZeroNuFit.Likelihood.get_mu_s_b
-ZeroNuFit.Likelihood.build_likelihood_zero_obs_evts
-ZeroNuFit.Likelihood.build_likelihood_per_partition
-ZeroNuFit.Likelihood.build_likelihood_looping_partitions
-ZeroNuFit.Likelihood.generate_data
-ZeroNuFit.Likelihood.get_signal_bkg_priors
-ZeroNuFit.Likelihood.build_prior
+ZeroNuFit.Utils.get_par_posterior
+ZeroNuFit.Utils.inverse_uniform_cdf
+ZeroNuFit.Utils.generate_disjoint_uniform_samples
+ZeroNuFit.Utils.save_generated_samples
+ZeroNuFit.Utils.save_results_into_json
 ```

src/analysis.jl

@@ -14,7 +14,21 @@
 """
     save_outputs(partitions, events, part_event_index, samples, posterior, nuisance_info, config, output_path, fit_ranges;priors=nothing,par_names=nothing,toy_idx=nothing)
 
-Function to plot and save results, as well as inputs
+Function to plot and save results, as well as inputs.
+
+### Arguments
+- `partitions`: table of partitions.
+- `events`: list of events (=energies) in each partition.
+- `part_event_index`: index mapping events to the partitions.
+- `samples`: set of generated MCMC samples.
+- `posterior`: posterior distribution evaluated via `PosteriorMeasure(likelihood, prior)`.
+- `nuisance_info`: dictionary with info on the prior parameters.
+- `config`: input dictionary.
+- `output_path`: output folder path.
+- `fit_ranges`: dictionary of energy ranges considered for the analysis.
+- `priors`: prior distributions.
+- `par_names`: collection of parameter names.
+- `toy_idx`: identification index of the generated toy.
 """
 function save_outputs(
     partitions,
@@ -125,15 +139,18 @@
 
 end
 
-# function to run the unbinned fit
+
+"""
+    run_analysis(config::Dict{String,Any}; output_path::String, toy_idx = nothing)
+
+Function which handeles running analysis.
+
+### Arguments
+- `config::Dict{String,Any}`: the fit configuration.
+- `output_path::String`: the path to the output files folder.
+- `toy_idx`: identification index of the generated toy.
+"""
 function run_analysis(config::Dict{String,Any}; output_path::String, toy_idx = nothing)
-    """
-    Function which handeles running analysis
-    Parameters:
-    ----------
-        config::Dict{String,Any} the fit configuration
-        output_path::String (keyword) the path to the output files folder
-    """
     @info "You entered into src/ZeroNuFit.jl"
 
     part_event_index, events, partitions, fit_ranges =
@@ -199,15 +216,15 @@
 end
 
 
-function retrieve_real_fit_results(config::Dict{String,Any})
-    """
-    Function which handeles generating of fake data
-    Parameters:
-    ----------
-        config::Dict{String,Any} the fit configuration
-        output_path::String (keyword) the path to the output files folder
-    """
+"""
+    retrieve_real_fit_results(config::Dict{String,Any})
+
+Function which handeles generating of fake data and run a signal+background model fit over it.
 
+### Arguments
+- `config::Dict{String,Any}`: the fit configuration.
+"""
+function retrieve_real_fit_results(config::Dict{String,Any})
     @info "You entered into src/ZeroNuFit.jl"
 
     @info"Let's retrieve some partitions ..."