Merge pull request #38 from Julia-Tempering/bib-refactor

Bib refactor

docs/make.jl

@@ -111,7 +111,7 @@ headless() do
             assets=String[],
             size_threshold = nothing # overrides default size limit for a single html file
         ),
-        plugins = InferenceReport.make_doc_plugins([InferenceReport.example_bib]),
+        plugins = InferenceReport.make_doc_plugins(InferenceReport.example_bib()),
         pages=[
             "User guide" => "index.md",
             "Examples" => run_examples(),

docs/src/index.md

@@ -96,7 +96,7 @@ nothing # hide
 Two methods are available to specify descriptions for target 
 distributions. 
 
-First, a markdown description can be passed in as argument:
+First, a [`TargetDescription`](@ref) can be passed in as argument:
 
 ```@example descriptions
 using InferenceReport
@@ -105,16 +105,16 @@ using Pigeons
 target = toy_mvn_target(2)
 pt = pigeons(; target, n_rounds = 2)
 
-report(pt; 
-    target_description = 
-        """
-        The model description can use math: ``x^2``. 
-        """)
+target_description = TargetDescription(
+    text = """
+    The model description can use math: ``x^2``. 
+    """)
+report(pt; target_description)
 
 nothing #hide
 ```
 
-But often, we may have a family of targets (e.g., in the above 
+Sometimes we may have a family of targets (e.g., in the above 
 example, normals 
 indexed by their dimensionality) and would like the 
 documentation to be automatically generated based on the parameters. 
@@ -130,13 +130,14 @@ target = toy_mvn_target(2)
 pt = pigeons(; target, n_rounds = 2)
 
 const MyTargetType = typeof(target)
-InferenceReport.pigeons_target_description(target::MyTargetType) = 
-    """
+InferenceReport.pigeons_target_description(target::MyTargetType) = TargetDescription(
+    text = """
     Some description. 
 
     It can use information in the target, e.g. here 
     to report that its dimension is: $(target.dim)
     """
+)
 
 nothing #hide
 ```
@@ -147,14 +148,14 @@ nothing #hide
 To create a bibliography, we provide automatic integration with 
 [DocumenterCitations](https://juliadocs.org/DocumenterCitations.jl/stable/). 
 
-In the target description, use a syntax like 
+In the target description's text, use a syntax like 
 ```
 [bib_key](@citet)
 ```
 to include a citation (see DocumenterCitations for 
 [more citation styles](https://juliadocs.org/DocumenterCitations.jl/stable/gallery/)). 
-Then pass the path to bibtex file(s) to 
-`report`'s  `bib_files` argument (takes a vector of strings). 
+Then pass include the contents of bibtex file to 
+[`pigeons_target_description`](@ref)'s  `bibliography` argument.
 
 ```@example bib
 using InferenceReport
@@ -164,17 +165,19 @@ target = toy_mvn_target(2)
 pt = pigeons(; target, n_rounds = 2)
 
 report(pt; 
-    bib_files = [InferenceReport.example_bib],
-    target_description = 
-        """
+    target_description = TargetDescription(
+        text = """
         The model description can use math: ``x^2``.
         Citation: [neal_slice_2003](@citet)
-        """)
+        """, 
+        bibliography = InferenceReport.example_bib()
+    ))
 
 nothing #hide
 ```
 
-See `Examples` in the left side bar to see examples of linked bibliographic 
+See `funnel_model` and `Bibliography` in the navigation bar to see examples 
+of linked bibliographic 
 items. 
 
 
@@ -210,8 +213,6 @@ nothing # hide
 
 
 
-
-
 ## Adding postprocessors 
 
 Calling `report()` triggers a list of postprocessors, each creating a section 

src/InferenceReport.jl

@@ -19,6 +19,7 @@ import Pigeons: @auto
 using DataFrames
 using DocumenterCitations
 
+include("TargetDescription.jl")
 include("ReportOptions.jl")
 include("Inference.jl")
 include("PostprocessContext.jl") 
@@ -63,7 +64,6 @@ function report(algo_or_chains, options::ReportOptions)
     context = PostprocessContext(inference, src_dir, String[], Dict{String,Any}(), options)
     add_key_value(context, "target_name", target_name(options.target_name, algo_or_chains))
     add_key_value(context, "original_dim", inference.original_dim)
-    add_key_value(context, "bib_files", options.bib_files)
     warn_if_truncated(context)
 
     for postprocessor in options.postprocessors 
@@ -146,8 +146,8 @@ function render(context)
         root = dirname(context.output_directory),
         sitename = "InferenceReport",
         format = context.options.writer,
-        pages = pages, 
-        plugins = make_doc_plugins(context.options.bib_files)
+        pages, 
+        plugins = make_doc_plugins(get_bib(context)) 
     )
     try
         makedocs(; makedocs_kwargs...)
@@ -203,6 +203,6 @@ include("utils.jl")
 include("processors.jl")
 include("make_index.jl")
 
-export report, @reproducible, cite!
+export report, @reproducible, cite!, TargetDescription
 
 end # module

src/ReportOptions.jl

@@ -21,11 +21,13 @@ $FIELDS
     target_name::Union{String, Nothing} = nothing
 
     """
-    Extended description of the target. If nothing, will attempt to 
+    Description of the target, specified 
+    using a [`TargetDescription`](@ref). 
+    If `nothing`, will attempt to 
     auto-detect it via [`target_description`](@ref) 
     and [`pigeons_target_description`](@ref).
     """
-    target_description::Union{String, Nothing} = nothing
+    target_description::Union{TargetDescription, Nothing} = nothing
 
     """
     If true, the report webpage's md files are rendered into html files.
@@ -76,9 +78,4 @@ $FIELDS
     processed.  
     """
     max_dim::Int = 10
-
-    """
-    Set of bib files to use for model descriptions.  
-    """
-    bib_files::Vector{String} = []
 end

src/TargetDescription.jl

@@ -0,0 +1,26 @@
+"""
+Description of a target.
+
+$FIELDS
+"""
+@kwdef struct TargetDescription
+
+    """
+    Keywords for the target.
+    """
+    keywords::Vector{String} = String[]
+
+    """
+    Contents of TeX `bib` file used to provide 
+    bibliographical references in the text, 
+    or `nothing` if no bibliography should be 
+    generated.
+    """
+    bibliography::Union{String,Nothing} = nothing
+
+    """
+    Description of the target.
+    """
+    text::String
+
+end

src/building_blocks.jl

@@ -83,12 +83,6 @@ function add_key_value(context, key, value)
     context.generated_dict[key] = value
 end
 
-function add_bib(context)
-    biblio = """
-    
-    """
-end
-
 """
 $SIGNATURES 
 """
@@ -108,15 +102,18 @@ pigeons_target_name(target) = string(target)
 """
 $SIGNATURES 
 """
-target_description(context::PostprocessContext) = 
+function target_description(context::PostprocessContext)
+    description = target_description(context.options.target_description, context.inference.algorithm)
+    add_key_value(context, "bibliography", description.bibliography)
     add_markdown(context; 
         title = "Description", 
-        contents = target_description(context.options.target_description, context.inference.algorithm)
+        contents = description.text
     )
+end
 
 target_description(unspecified_description::Nothing, pt::PT) = pigeons_target_description(pt.inputs.target)
 target_description(unspecified_description::Nothing, _) = throw("no description provided")
-target_description(specified_description::String, _) = specified_description 
+target_description(specified_description::TargetDescription, _) = specified_description
 
 """
 $SIGNATURES 
@@ -129,7 +126,10 @@ pigeons_target_description(target, _) = throw("no description provided")
 
 # Some examples below of how to create description:
 
-pigeons_target_description(target, ::Val{:toy_turing_unid_model}) =
+pigeons_target_description(target, ::Val{:toy_turing_unid_model}) = TargetDescription(
+    keywords = ["pigeons builtin"],
+    bibliography = example_bib(),
+    text = 
     """
     Consider a Bayesian model where the likelihood is a binomial distribution with probability parameter ``p``. 
     Let us consider an over-parameterized model where we 
@@ -160,69 +160,82 @@ pigeons_target_description(target, ::Val{:toy_turing_unid_model}) =
     unidentifiable models concentrate on a sub-manifold, 
     making sampling difficult, as shown in the following pair plots.
     """
+    )
 
-const example_bib = dirname(dirname(pathof(InferenceReport))) * "/test/supporting/refs.bib"
+example_bib() = read(dirname(dirname(pathof(InferenceReport))) * "/test/supporting/refs.bib", String)
 
 function pigeons_target_description(target, ::Val{:funnel_model})
     # StanLogPotential's data is a bit more ackward to access:
     data = JSON.parse(target.data.data) 
     dim = data["dim"]
     scale = data["scale"]
-    """
-    A synthetic target introduced 
-    in [neal_slice_2003](@citet)
-    to benchmark algorithms on situations where the local curvature of the target density 
-    varies from one part of the space to another. Specifically, the shape of the target 
-    (see pair plots below) is such that when ``y < 0``, the posterior is very narrow 
-    while for ``y > 0`` it is wide. 
-
-    The funnel is formally defined as follows:
-    
-    ```math
-    \\begin{aligned}
-    y &\\sim \\text{Normal}(0, 3) \\\\
-    x_i &\\sim \\text{Normal}(0, \\exp(y / \\text{scale})) \\;\\text{ for }i \\in \\{1, \\dots, d\\}  \\\\
-    \\end{aligned}
-    ```
-
-    Here we use the values: 
-
-    | Parameter                           | Value                            | 
-    |:----------------------------------- | :------------------------------- |
-    | Number of "``x``" dimensions, ``d`` | $(dim)                           |
-    | Scale factor                        | $(scale)                         |
-    
-    While the example is artificial, it is useful since it combines certain features 
-    present in many real challenging targets (varying local curvature), while having 
-    known moments for the difficult dimension to explore, ``y`` (since ``y`` is 
-    marginally a normal distribution with known moments). 
-
-    [Stan implementation](https://github.com/Julia-Tempering/Pigeons.jl/blob/main/examples/stan/funnel.stan)
-    """
+    return TargetDescription(
+        keywords = ["pigeons builtin"],
+        bibliography = example_bib(),
+        text = 
+        """
+        A synthetic target introduced 
+        in [neal_slice_2003](@citet)
+        to benchmark algorithms on situations where the local curvature of the target density 
+        varies from one part of the space to another. Specifically, the shape of the target 
+        (see pair plots below) is such that when ``y < 0``, the posterior is very narrow 
+        while for ``y > 0`` it is wide. 
+
+        The funnel is formally defined as follows:
+        
+        ```math
+        \\begin{aligned}
+        y &\\sim \\text{Normal}(0, 3) \\\\
+        x_i &\\sim \\text{Normal}(0, \\exp(y / \\text{scale})) \\;\\text{ for }i \\in \\{1, \\dots, d\\}  \\\\
+        \\end{aligned}
+        ```
+
+        Here we use the values: 
+
+        | Parameter                           | Value                            | 
+        |:----------------------------------- | :------------------------------- |
+        | Number of "``x``" dimensions, ``d`` | $(dim)                           |
+        | Scale factor                        | $(scale)                         |
+        
+        While the example is artificial, it is useful since it combines certain features 
+        present in many real challenging targets (varying local curvature), while having 
+        known moments for the difficult dimension to explore, ``y`` (since ``y`` is 
+        marginally a normal distribution with known moments). 
+
+        [Stan implementation](https://github.com/Julia-Tempering/Pigeons.jl/blob/main/examples/stan/funnel.stan)
+        """)
 end
 
 function pigeons_target_description(target, ::Val{:banana_model})
     # StanLogPotential's data is a bit more ackward to access:
     data = JSON.parse(target.data.data) 
     dim = data["dim"]
     scale = data["scale"]
-    """
-    A common synthetic distribution used to benchmark MCMC methods. 
-    For details on this implementation, 
-    see [pagani_n-dimensional_2022](@citet). 
-
-    Here we use the values: 
-
-    | Parameter                           | Value                            | 
-    |:----------------------------------- | :------------------------------- |
-    | Number of "``y``" dimensions, ``d`` | $(dim)                           |
-    | Scale factor                        | $(scale)                         |
-
-    [Stan implementation](https://github.com/Julia-Tempering/Pigeons.jl/blob/main/examples/stan/banana.stan)
-    """
+    return TargetDescription(
+        keywords = ["pigeons builtin"],
+        bibliography = example_bib(),
+        text = 
+        """
+        A common synthetic distribution used to benchmark MCMC methods. 
+        For details on this implementation, 
+        see [pagani_n-dimensional_2022](@citet). 
+
+        Here we use the values: 
+
+        | Parameter                           | Value                            | 
+        |:----------------------------------- | :------------------------------- |
+        | Number of "``y``" dimensions, ``d`` | $(dim)                           |
+        | Scale factor                        | $(scale)                         |
+
+        [Stan implementation](https://github.com/Julia-Tempering/Pigeons.jl/blob/main/examples/stan/banana.stan)
+        """
+    )
 end
 
-pigeons_target_description(target, ::Val{:eight_schools_centered_model}) =
+pigeons_target_description(target, ::Val{:eight_schools_centered_model}) = TargetDescription(
+    keywords = ["pigeons builtin"],
+    bibliography = example_bib(),
+    text = 
     """
     A common posterior distribution, based on data from [rubin_estimation_1981](@citet)
     used to to illustrate hierarchical 
@@ -236,6 +249,7 @@ pigeons_target_description(target, ::Val{:eight_schools_centered_model}) =
     [Stan implementation](https://github.com/Julia-Tempering/Pigeons.jl/blob/main/examples/stan/eight_schools_centered.stan)
     [Data](https://github.com/Julia-Tempering/Pigeons.jl/blob/main/examples/stan/eight_schools.json)
     """
+    )
 
 
 """