Public API

This page lists exported symbols of CTBase.DevTools.

---

From CTBase.DevTools

CTBase.DevTools [Module]

CTBase.DevTools Module

DevTools

Developer tools for CTBase with tag-based dispatch.

This module provides the extension point infrastructure for internal control-toolbox development tools: test running, API documentation generation, documentation helpers, and coverage post-processing.

AbstractCoveragePostprocessingTag [Abstract Type]

CTBase.DevTools.AbstractCoveragePostprocessingTag Type

abstract type AbstractCoveragePostprocessingTag

Abstract supertype for tags used to select a particular implementation of postprocess_coverage.

Concrete subtypes identify a specific backend that provides the actual coverage post-processing logic.

Example

julia> using CTBase

julia> CTBase.DevTools.CoveragePostprocessingTag() isa CTBase.DevTools.AbstractCoveragePostprocessingTag
true

AbstractDocumenterReferenceTag [Abstract Type]

CTBase.DevTools.AbstractDocumenterReferenceTag Type

abstract type AbstractDocumenterReferenceTag

Abstract supertype for tags used to select a particular implementation of automatic_reference_documentation.

Concrete subtypes identify a specific backend that provides the actual documentation generation logic.

Example

julia> using CTBase

julia> CTBase.DevTools.DocumenterReferenceTag() isa CTBase.DevTools.AbstractDocumenterReferenceTag
true

AbstractTestRunnerTag [Abstract Type]

CTBase.DevTools.AbstractTestRunnerTag Type

abstract type AbstractTestRunnerTag

Abstract supertype for tags used to select a particular implementation of run_tests.

Concrete subtypes identify a specific backend that provides the actual test runner logic.

Example

julia> using CTBase

julia> CTBase.DevTools.TestRunnerTag() isa CTBase.DevTools.AbstractTestRunnerTag
true

See also: CTBase.DevTools.TestRunnerTag

CoveragePostprocessingTag [Struct]

CTBase.DevTools.CoveragePostprocessingTag Type

struct CoveragePostprocessingTag <: CTBase.DevTools.AbstractCoveragePostprocessingTag

Concrete tag type used to dispatch to the CoveragePostprocessing extension.

Instances of this type are passed to postprocess_coverage to enable coverage post-processing when the extension is available.

Example

julia> using CTBase

julia> CTBase.DevTools.CoveragePostprocessingTag() isa CTBase.DevTools.AbstractCoveragePostprocessingTag
true

See also: CTBase.DevTools.AbstractCoveragePostprocessingTag

DocumenterReferenceTag [Struct]

CTBase.DevTools.DocumenterReferenceTag Type

struct DocumenterReferenceTag <: CTBase.DevTools.AbstractDocumenterReferenceTag

Concrete tag type used to dispatch to the DocumenterReference extension.

Instances of this type are passed to automatic_reference_documentation to enable the integration with Documenter.jl when the DocumenterReference extension is available.

Example

julia> using CTBase

julia> tag = CTBase.DevTools.DocumenterReferenceTag()
CTBase.DevTools.DocumenterReferenceTag()

TestRunnerTag [Struct]

CTBase.DevTools.TestRunnerTag Type

struct TestRunnerTag <: CTBase.DevTools.AbstractTestRunnerTag

Concrete tag type used to dispatch to the TestRunner extension.

Instances of this type are passed to run_tests to enable the extension-based test runner when the extension is available.

Example

julia> using CTBase

julia> tag = CTBase.DevTools.TestRunnerTag()
CTBase.DevTools.TestRunnerTag()

See also: CTBase.DevTools.AbstractTestRunnerTag

automatic_reference_documentation [Function]

CTBase.DevTools.automatic_reference_documentation Function

automatic_reference_documentation(
    ::CTBase.DevTools.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(
    ::CTBase.DevTools.DocumenterReferenceTag;
    subdirectory,
    primary_modules,
    sort_by,
    exclude,
    public,
    private,
    title,
    title_in_menu,
    filename,
    source_files,
    include_without_source,
    external_modules_to_document,
    public_title,
    private_title,
    public_description,
    private_description
)

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::String: 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::Function: a custom sort function applied to symbol lists.

• exclude::Vector{Symbol}: vector of symbol names to skip from the generated API.

• public::Bool: flag to generate public API page (default: true).

• private::Bool: flag to generate private API page (default: true).

• title::String: title displayed at the top of the generated page.

• title_in_menu::String: title displayed in the navigation menu (default: same as title).

• filename::String: base filename (without extension) for the markdown file.

• source_files::Vector{String}: global source file paths (fallback if no module-specific files). Deprecated: prefer using primary_modules=[Module => files] instead.

• include_without_source::Bool: if true, include symbols whose source file cannot be determined. Default: false.

• external_modules_to_document::Vector{Module}: additional modules to search for docstrings (e.g., [Plots] to include Plots.plot methods defined in your source files).

• public_title::String: custom title for public API page. Empty string uses default ("Public API" or "Public").

• private_title::String: custom title for private API page. Empty string uses default ("Private API" or "Private").

• public_description::String: custom description text for public API page. Empty string uses default.

• private_description::String: custom description text for private API page. Empty string uses default.

Returns

• Pair: structure suitable for Documenter.makedocs pages argument.

Throws

• CTBase.Exceptions.IncorrectArgument: if both public and private are false.

Notes

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

postprocess_coverage [Function]

CTBase.DevTools.postprocess_coverage Function

postprocess_coverage(
    ::CTBase.DevTools.AbstractCoveragePostprocessingTag;
    generate_report,
    root_dir,
    dest_dir,
    worst_n_files,
    max_uncovered_lines
)

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.

• worst_n_files::Int=20: Maximum number of lowest-covered files to list in the report.

• max_uncovered_lines::Int=200: Maximum number of uncovered lines to display in the report.

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()

postprocess_coverage(
    ::CTBase.DevTools.CoveragePostprocessingTag;
    generate_report,
    root_dir,
    dest_dir,
    worst_n_files,
    max_uncovered_lines
)

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.

• worst_n_files::Int=20: Maximum number of lowest-covered files to list in the report.

• max_uncovered_lines::Int=200: Maximum number of uncovered lines to display in the report.

Returns

• Nothing

Notes

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

Example

using CTBase

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

repl_without_extensions [Function]

CTBase.DevTools.repl_without_extensions Function

repl_without_extensions(
    ::CTBase.DevTools.AbstractDocumenterReferenceTag,
    package::Symbol,
    codes::AbstractString...;
    kwargs...
) -> Markdown.MD

REPL transcript of codes evaluated in a fresh Julia process where only package is loaded, rendered like an @repl block. The last snippet must throw; its error is the output. Use it from an @eval block to show an error that only exists when an extension is not loaded:

```@eval
CTBase.DevTools.repl_without_extensions(:MyPackage, "MyPackage.Solver()")
```

make.jl loads every weak dependency so that the API reference documents the extensions, and extension methods are global to the process: an @repl block would show a working instance instead of the error.

This method is an extension point: it throws an CTBase.Exceptions.ExtensionError unless the DocumenterReference extension is loaded.

Arguments

• package::Symbol: the package loaded in the fresh process (using package: package).

• codes::AbstractString...: snippets evaluated in order in Main. All but the last are shown as inputs and must succeed (e.g. using statements); the last one must throw.

Keyword Arguments

• project::AbstractString: the environment of the fresh process. Default: the active project (the docs environment when make.jl runs with --project=docs).

Returns

• Markdown.MD: an ansi code block with a julia-repl-runs spec, rendered by DocumenterVitepress with Julia-highlighted inputs and ANSI-colored output.

Throws

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

• CTBase.Exceptions.IncorrectArgument: If the last snippet does not throw, so that an example that no longer shows an error fails the build.

• Base.ProcessFailedException: If a snippet before the last one throws.

See also: CTBase.DevTools.warnings_without_paths.

repl_without_extensions(
    package::Symbol,
    codes::AbstractString...;
    kwargs...
) -> Markdown.MD

Convenience wrapper for repl_without_extensions using the default backend tag.

Example

```@eval
CTBase.DevTools.repl_without_extensions(:MyPackage, "MyPackage.Solver()")
```

run_tests [Function]

CTBase.DevTools.run_tests Function

run_tests(
    ::CTBase.DevTools.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.DevTools.TestRunnerTag;
    args,
    testset_name,
    available_tests,
    excluded_tests,
    filename_builder,
    funcname_builder,
    eval_mode,
    verbose,
    showtiming,
    test_dir,
    on_test_start,
    on_test_done,
    show_progress_line,
    show_progress_bar,
    progress_bar_threshold
) -> Union{Nothing, Test.FallbackTestSet, Test.DefaultTestSet}

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

Arguments

• ::CTBase.DevTools.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

• excluded_tests: Tests to remove from the available tests (Symbols, Strings, or glob patterns)

• 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)

• show_progress_line::Bool: Show progress line with symbol, index, spec, and time (default: true)

• show_progress_bar::Bool: Show graphical progress bar [█░░░...] within the line (default: true)

• progress_bar_threshold::Int: Maximum tests for full-resolution progress bar (default: 100)

Returns

• Nothing: Tests are executed via side effects

Notes

• Test selection is driven by args (coverage flags are automatically filtered out)

• excluded_tests is applied after available_tests or auto-discovery and before args

• 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, it replaces the built-in progress callback; show_progress_line is then ignored

• When show_progress_line=true but show_progress_bar=false, displays minimal output: ✓ [01/76] suite/test.jl (0.2s) without the graphical bar

Example

julia> using CTBase: TestRunner

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

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

See also: CTBase.DevTools.run_tests

warnings_without_paths [Function]

CTBase.DevTools.warnings_without_paths Function

warnings_without_paths(
    f,
    ::CTBase.DevTools.AbstractDocumenterReferenceTag;
    kwargs...
) -> Any

Evaluate f() with its warnings captured, print them without source location, and return the value of f(). Use it on hidden lines around the visible lines of an @example block:

```@example page
CTBase.DevTools.warnings_without_paths(; show = true) do # hide
MyPackage.Solver(unknown_option = 1; mode = :permissive)
end # hide
```

In an @example block, Documenter prints a log record with its source location (└ @ Module /path/on/the/build/machine/file.jl:line), which publishes local or CI paths. Here each warning is printed as ┌ Warning: … / │ … / └ @ Module.

Documenter does not show what a block printed when the block returns a value. With show = true, the value is printed after the warnings and nothing is returned, so both appear. Variables assigned inside the block must be declared global on a hidden line.

This method is an extension point: it throws an CTBase.Exceptions.ExtensionError unless the DocumenterReference extension is loaded.

Keyword Arguments

• show::Bool: print the value of f() (as the REPL would) and return nothing. Default: false.

Returns

• The value of f(), or nothing when show = true.

Throws

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

See also: CTBase.DevTools.repl_without_extensions.

warnings_without_paths(f; kwargs...) -> Any

Convenience wrapper for warnings_without_paths using the default backend tag.

Example

```@example page
CTBase.DevTools.warnings_without_paths() do # hide
MyPackage.Solver(unknown_option = 1; mode = :permissive)
end # hide
```