Public API

Extensions

Extension system for CTBase with tag-based dispatch.

This module provides the extension point infrastructure used throughout the CTBase ecosystem, including abstract tags, concrete implementations, and extension functions.

automatic_reference_documentation(
    ::CTBase.Extensions.AbstractDocumenterReferenceTag;
    kwargs...
)

Generate API reference documentation pages for one or more modules.

This method is an extension point: the default implementation throws an CTBase.Exceptions.ExtensionError unless a backend extension providing the actual implementation is loaded (e.g. the DocumenterReference extension).

Keyword Arguments

Forwarded to the active backend implementation.

Throws

• CTBase.Exceptions.ExtensionError: If no backend extension is loaded.

Example

using CTBase
# Requires DocumenterReference extension to be active
automatic_reference_documentation(
    subdirectory="api",
    primary_modules=[MyModule],
    title="My API"
)

automatic_reference_documentation(; kwargs...)

Convenience wrapper for automatic_reference_documentation using the default backend tag.

Keyword Arguments

Forwarded to automatic_reference_documentation(DocumenterReferenceTag(); kwargs...).

Throws

• CTBase.Exceptions.ExtensionError: If the required backend extension is not loaded.

Example

using CTBase
# automatic_reference_documentation(subdirectory="api")

automatic_reference_documentation(;
    subdirectory::String,
    primary_modules,
    sort_by::Function = identity,
    exclude::Vector{Symbol} = Symbol[],
    public::Bool = true,
    private::Bool = true,
    title::String = "API Reference",
    title_in_menu::String = "",
    filename::String = "",
    source_files::Vector{String} = String[],
    include_without_source::Bool = false,
    external_modules_to_document::Vector{Module} = Module[],
    public_title::String = "",
    private_title::String = "",
    public_description::String = "",
    private_description::String = "",
)

Automatically creates the API reference documentation for one or more modules and returns a structure which can be used in the pages argument of Documenter.makedocs.

Arguments

• subdirectory: the directory relative to the documentation root in which to write the API files.
• primary_modules: a vector of modules or Module => source_files pairs to document. When source files are provided, only symbols defined in those files are documented.
• sort_by: a custom sort function applied to symbol lists.
• exclude: vector of symbol names to skip from the generated API.
• public: flag to generate public API page (default: true).
• private: flag to generate private API page (default: true).
• title: title displayed at the top of the generated page.
• title_in_menu: title displayed in the navigation menu (default: same as title).
• filename: base filename (without extension) for the markdown file.
• source_files: global source file paths (fallback if no module-specific files). Deprecated: prefer using primary_modules=[Module => files] instead.
• include_without_source: if true, include symbols whose source file cannot be determined. Default: false.
• external_modules_to_document: additional modules to search for docstrings (e.g., [Plots] to include Plots.plot methods defined in your source files).
• public_title: custom title for public API page. Empty string uses default ("Public API" or "Public").
• private_title: custom title for private API page. Empty string uses default ("Private API" or "Private").
• public_description: custom description text for public API page. Empty string uses default.
• private_description: custom description text for private API page. Empty string uses default.

Multiple instances

Each time you call this function, a new object is added to the global variable DocumenterReference.CONFIG. Use reset_config!() to clear it between builds.

postprocess_coverage(
    ::CTBase.Extensions.AbstractCoveragePostprocessingTag;
    generate_report,
    root_dir,
    dest_dir
)

Post-process coverage artifacts produced by Pkg.test(; coverage=true).

This is an extension point: the default implementation throws an CTBase.Exceptions.ExtensionError unless a backend extension (e.g. CoveragePostprocessing) is loaded.

Keyword Arguments

• generate_report::Bool=true: Whether to generate summary reports.
• root_dir::String=pwd(): Project root directory used to locate coverage artifacts.
• dest_dir::String="coverage": Destination directory for coverage artifacts.

Throws

• CTBase.Exceptions.ExtensionError: If the coverage post-processing extension is not loaded.

Example

using CTBase
# postprocess_coverage(generate_report=true)

postprocess_coverage(; kwargs...)

Convenience wrapper for postprocess_coverage using the default backend tag.

Keyword Arguments

Forwarded to postprocess_coverage(CoveragePostprocessingTag(); kwargs...).

Throws

• CTBase.Exceptions.ExtensionError: If the coverage post-processing extension is not loaded.

Example

using CTBase
# postprocess_coverage()

CTBase.postprocess_coverage(::CTBase.Extensions.CoveragePostprocessingTag; generate_report::Bool=true, root_dir::String=pwd())

Post-process coverage artifacts produced by Pkg.test(; coverage=true).

This implementation:

• Collects coverage source directories under root_dir (src/, test/, ext/ when present)
• Resets the coverage/ directory
• Removes stale .cov files (keeping the most complete PID suffix when multiple runs exist)
• Optionally generates reports (LCOV + markdown report)
• Moves .cov files into coverage/cov/ (recursively from source dirs)

Keyword Arguments

• generate_report::Bool=true: If true, write coverage/lcov.info and coverage/cov_report.md.
• root_dir::String=pwd(): Root directory of the project.
• dest_dir::String="coverage": Destination directory for coverage artifacts.

Returns

• Nothing

Notes

This function creates/removes/moves files and directories under root_dir.

Usage sketch (non-executed)

using CTBase

# CTBase.postprocess_coverage(; generate_report=true, root_dir=pwd())

run_tests(
    ::CTBase.Extensions.AbstractTestRunnerTag;
    kwargs...
) -> Union{Nothing, Test.FallbackTestSet, Test.DefaultTestSet}

Run the project test suite using an extension-provided test runner.

This is an extension point: the default implementation throws an CTBase.Exceptions.ExtensionError unless a backend extension is loaded.

Keyword Arguments

Forwarded to the active backend implementation.

Throws

• CTBase.Exceptions.ExtensionError: If the test runner extension is not loaded.

Example

using CTBase
# run_tests()

run_tests(
;
    kwargs...
) -> Union{Nothing, Test.FallbackTestSet, Test.DefaultTestSet}

Convenience wrapper for run_tests using the default backend tag.

Keyword Arguments

Forwarded to run_tests(TestRunnerTag(); kwargs...).

Throws

• CTBase.Exceptions.ExtensionError: If the test runner extension is not loaded.

Example

using CTBase
# run_tests()

run_tests(
    ::CTBase.Extensions.TestRunnerTag;
    args,
    testset_name,
    available_tests,
    filename_builder,
    funcname_builder,
    eval_mode,
    verbose,
    showtiming,
    test_dir,
    on_test_start,
    on_test_done,
    progress
) -> Union{Nothing, Test.FallbackTestSet, Test.DefaultTestSet}

Run tests with configurable file/function name builders and optional available tests filter.

Arguments

• ::CTBase.Extensions.TestRunnerTag: Dispatch tag for the TestRunner extension
• args::AbstractVector{<:AbstractString}: Command-line arguments (typically String.(ARGS))
• testset_name::String: Name of the main testset (default: "Tests")
• available_tests: Allowed tests (Symbols, Strings, or glob patterns). Empty = auto-discovery
• filename_builder::Function: name → filename mapping (default: identity)
• funcname_builder::Function: name → function_name mapping (default: identity)
• eval_mode::Bool: Whether to call the function after include (default: true)
• verbose::Bool: Verbose @testset output (default: true)
• showtiming::Bool: Show timing in @testset output (default: true)
• test_dir::String: Root directory for test files (default: joinpath(pwd(), "test"))
• on_test_start::Union{Function,Nothing}: Callback before eval (default: nothing)
• on_test_done::Union{Function,Nothing}: Callback after eval (default: nothing)
• progress::Bool: Show built-in progress bar (default: true)

Returns

• Nothing: Tests are executed via side effects

Notes

• Test selection is driven by args (coverage flags are automatically filtered out)
• Selection arguments are interpreted as glob patterns and matched against both test names and filenames
• Arguments starting with test/ are automatically stripped for convenience
• When on_test_done is provided, the built-in progress bar is disabled unless progress=true

Example

julia> using CTBase.TestRunner

julia> # Run all tests with default settings
julia> CTBase.run_tests()

julia> # Run specific tests with custom callbacks
julia> CTBase.run_tests(;
           args=["utils", "core"],
           on_test_start = info -> (println("Running: ", info.spec); true),
           on_test_done = info -> println("Done: ", info.status)
       )

See also: TestRunner.TestRunInfo, TestRunner._parse_test_args, TestRunner._select_tests