Private API

APIBuilder <: Documenter.Builder.DocumentPipeline

Custom Documenter pipeline stage for automatic API reference generation.

This builder is inserted into the Documenter pipeline at order 0.0 (before most other stages) to generate API reference pages from the configurations stored in CONFIG.

CONFIG::Vector{_Config}

Global configuration storage for API reference generation.

Each call to automatic_reference_documentation appends a new _Config entry to this vector. Use reset_config! to clear it between builds.

DOCTYPE_NAMES::Dict{DocType, String}

Mapping from DocType enum values to their human-readable string representations.

DOCTYPE_ORDER::Dict{DocType, Int}

Ordering for DocType values used when sorting symbols for display. Lower values appear first.

DocType

Enumeration of documentation element types recognized by the API reference generator.

Values

• DOCTYPE_ABSTRACT_TYPE: An abstract type declaration
• DOCTYPE_CONSTANT: A constant binding (including non-function, non-type values)
• DOCTYPE_FUNCTION: A function or callable
• DOCTYPE_MACRO: A macro (name starts with @)
• DOCTYPE_MODULE: A submodule
• DOCTYPE_STRUCT: A concrete struct type

PAGE_CONTENT_ACCUMULATOR::Dict{String, Vector{Tuple{Module, Vector{String}, Vector{String}}}}

Global accumulator for multi-module combined pages. Maps output filename to a list of (module, publicdocstrings, privatedocstrings) tuples.

_Config

Internal configuration for API reference generation.

Fields

• current_module::Module: The module being documented.
• subdirectory::String: Output directory for generated API pages.
• modules::Dict{Module,Vector{String}}: Mapping of modules to their source files. When a module is specified as Module => files, the files are stored here.
• sort_by::Function: Custom sort function for symbols.
• exclude::Set{Symbol}: Symbol names to exclude from documentation.
• public::Bool: Flag to generate public API page.
• private::Bool: Flag to generate private API page.
• title::String: Title displayed at the top of the generated page.
• title_in_menu::String: Title displayed in the navigation menu.
• source_files::Vector{String}: Global source file paths (fallback if no module-specific files).
• filename::String: Base filename (without extension) for the markdown file.
• include_without_source::Bool: If true, include symbols whose source file cannot be determined.
• external_modules_to_document::Vector{Module}: Additional modules to search for docstrings.

_build_api_page(document::Documenter.Document, config::_Config)

Generate public and/or private API reference pages for a module. Accumulates content in PAGE_CONTENT_ACCUMULATOR for later finalization.

_build_page_path(subdirectory::String, filename::String) -> String

Build the page path by joining subdirectory and filename. Handles special cases where subdirectory is "." or empty.

_build_page_return_structure(title_in_menu, subdirectory, filename, public, private) -> Pair

Build the return structure for automatic_reference_documentation.

_build_private_page_content(modules_str, module_contents) -> Tuple{String, Vector{String}}

Build the overview and docstrings for a private API page.

_build_public_page_content(modules_str, module_contents) -> Tuple{String, Vector{String}}

Build the overview and docstrings for a public API page.

_classify_symbol(obj, name_str::String) -> DocType

Classify a symbol by its type (function, macro, struct, constant, module, abstract type).

_collect_external_module_docstrings(config::_Config) -> Vector{String}

Collect docstrings for methods from external modules defined in source files.

_collect_methods_from_source_files(mod::Module, source_files::Vector{String}) -> Dict{Symbol, Vector{Method}}

Collect all methods from a module that are defined in the given source files.

_collect_module_docstrings(config::_Config, symbol_list) -> Vector{String}

Collect docstring blocks for symbols from the current module.

_collect_private_docstrings(config::_Config, symbol_list) -> Vector{String}

Collect docstring blocks for private symbols, including external module methods.

_default_basename(filename::String, public::Bool, private::Bool) -> String

Compute the default base filename for the generated markdown file.

_default_title(public::Bool, private::Bool) -> String

Compute the default title based on public/private flags.

_exported_symbols(mod::Module) -> NamedTuple

Classify all symbols in a module into exported and private categories. Returns a NamedTuple with exported and private fields, each containing sorted lists of (Symbol, DocType) pairs.

_finalize_api_pages(document::Documenter.Document)

Finalize all accumulated API pages by combining content from multiple modules.

_format_datatype_for_docs(T::DataType) -> String

Format a DataType for use in @docs blocks.

_format_type_for_docs(T) -> String

Format a type for use in Documenter's @docs block. Always fully qualifies types to avoid UndefVarError when Documenter evaluates in Main.

_format_type_param(p) -> String

Format a type parameter (can be a type or a value like an integer).

_get_effective_source_files(config::_Config) -> Vector{String}

Determine the effective source files for filtering symbols. Priority: module-specific files > global source_files > empty (no filtering).

_get_source_file(mod::Module, key::Symbol, type::DocType) -> Union{String, Nothing}

Determine the source file path where a symbol is defined. Returns nothing if the source file cannot be determined.

_get_source_from_docstring(mod::Module, key::Symbol) -> Union{String, Nothing}

Try to get source file path from docstring metadata.

_get_source_from_methods(obj) -> Union{String, Nothing}

Try to get source file path from method definitions.

_has_documentation(mod::Module, key::Symbol, type::DocType, modules::Dict) -> Bool

Check if a symbol has documentation. Logs a warning if not.

_iterate_over_symbols(f, config, symbol_list)

Iterate over symbols, applying a function to each documented symbol. Filters symbols based on exclusion list, documentation presence, and source files.

_method_signature_string(m::Method, mod::Module, key::Symbol) -> String

Generate a Documenter-compatible signature string for a method. Returns a string like Module.func(::Type1, ::Type2) for use in @docs blocks.

_normalize_paths(paths) -> Vector{String}

Normalize a collection of paths to absolute paths.

_parse_primary_modules(primary_modules::Vector) -> Dict{Module, Vector{String}}

Parse the primary_modules argument into a dictionary mapping modules to their source files. Handles both plain modules and Module => files pairs.

_passes_source_filter(mod, key, type, source_files, include_without_source) -> Bool

Check if a symbol passes the source file filter.

_register_config(current_module, subdirectory, modules, sort_by, exclude, public, private, 
                 title, title_in_menu, source_files, filename, include_without_source, 
                 external_modules_to_document)

Create and register a _Config in the global CONFIG vector.

_to_string(x::DocType) -> String

Convert a DocType enumeration value to its string representation.

reset_config!()

Clear the global CONFIG vector and PAGE_CONTENT_ACCUMULATOR. Useful between documentation builds or for testing.

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[],
)

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

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.