[docs] make a single public API page

docs/DocumenterReference.jl

@@ -0,0 +1,234 @@
+#  Copyright 2023, Oscar Dowson and contributors
+#  This Source Code Form is subject to the terms of the Mozilla Public
+#  License, v. 2.0. If a copy of the MPL was not distributed with this
+#  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+module DocumenterReference
+
+import Documenter
+import Markdown
+import MarkdownAST
+
+@enum(
+    DocType,
+    DOCTYPE_ABSTRACT_TYPE,
+    DOCTYPE_CONSTANT,
+    DOCTYPE_FUNCTION,
+    DOCTYPE_MACRO,
+    DOCTYPE_MODULE,
+    DOCTYPE_STRUCT,
+)
+
+struct _Config
+    current_module::Module
+    subdirectory::String
+    modules::Dict{Module,<:Vector}
+    sort_by::Function
+    filter::Function
+end
+
+const CONFIG = _Config[]
+
+abstract type APIBuilder <: Documenter.Builder.DocumentPipeline end
+
+Documenter.Selectors.order(::Type{APIBuilder}) = 0.0
+
+"""
+    automatic_reference_documentation(;
+        subdirectory::String,
+        modules::Dict{Module,Vector{Pair{String,DocType}}},
+        sort_by::Function = identity,
+        filter::Function = _ -> true,
+    )
+
+Automatically creates the API reference documentation for `current_module` and
+returns a `Vector` which can be used in the `pages` argument of
+`Documenter.makedocs`.
+
+## Arguments
+
+ * `current_module`: the module from which to create an API reference.
+ * `subdirectory`: the directory relative to the documentation root in which to
+   write the API files.
+ * `modules`: a dictionary mapping modules to a vector of non-exported
+   docstrings to include in the API reference. Each element is a pair which maps
+   the docstring signature to a [`DocumenterReference.DocType`](@ref) enum.
+
+## Multiple instances
+
+Each time you call this function, a new object is added to the global variable
+`DocumenterReference.CONFIG`.
+"""
+function automatic_reference_documentation(;
+    subdirectory::String,
+    modules::Vector,
+    sort_by::Function = identity,
+    filter::Function = _ -> true,
+)
+    _to_extras(m::Module) = m => Any[]
+    _to_extras(m::Pair) = m
+    _modules = Dict(_to_extras(m) for m in modules)
+    list_of_pages = Any[]
+    for m in modules
+        current_module = first(_to_extras(m))
+        pages = _automatic_reference_documentation(
+            current_module;
+            subdirectory,
+            modules = _modules,
+            sort_by,
+            filter,
+        )
+        push!(list_of_pages, "$current_module" => pages)
+    end
+    return "API Reference" => list_of_pages
+end
+
+function _automatic_reference_documentation(
+    current_module::Module;
+    subdirectory::String,
+    modules::Dict{Module,<:Vector},
+    sort_by::Function,
+    filter::Function,
+)
+    config = _Config(current_module, subdirectory, modules, sort_by, filter)
+    push!(CONFIG, config)
+    return "$subdirectory/$current_module.md"
+end
+
+function _exported_symbols(mod, config)
+    contents = Pair{Symbol,DocType}[]
+    for n in filter(config.filter, names(mod; all = true))
+        f = getfield(mod, n)
+        f_str = string(f)
+        if startswith(f_str, "@")
+            push!(contents, n => DOCTYPE_MACRO)
+        elseif startswith(f_str, "Abstract")
+            push!(contents, n => DOCTYPE_ABSTRACT_TYPE)
+        elseif f isa Type
+            push!(contents, n => DOCTYPE_STRUCT)
+        elseif f isa Function
+            if islowercase(f_str[1])
+                push!(contents, n => DOCTYPE_FUNCTION)
+            else
+                push!(contents, n => DOCTYPE_STRUCT)
+            end
+        elseif f isa Module
+            push!(contents, n => DOCTYPE_MODULE)
+        else
+            push!(contents, n => DOCTYPE_CONSTANT)
+        end
+    end
+    order = Dict(
+        DOCTYPE_MODULE => 0,
+        DOCTYPE_MACRO => 1,
+        DOCTYPE_FUNCTION => 2,
+        DOCTYPE_ABSTRACT_TYPE => 3,
+        DOCTYPE_STRUCT => 4,
+        DOCTYPE_CONSTANT => 5,
+    )
+    return sort(contents; by = x -> (order[x[2]], "$(x[1])"))
+end
+
+function _iterate_over_symbols(f, config)
+    current_module = config.current_module
+    modules = get(config.modules, config.current_module, Any[])
+    key_types = vcat(_exported_symbols(current_module, config), modules)
+    for (key, type) in key_types
+        if key isa Symbol
+            doc = Base.Docs.doc(Base.Docs.Binding(current_module, key))
+            if occursin("No documentation found.", string(doc))
+                if type == DOCTYPE_MODULE
+                    mod = getfield(current_module, key)
+                    if mod == current_module || !haskey(config.modules, mod)
+                        continue
+                    end
+                else
+                    error("Documentation missing for $key")
+                end
+            end
+        end
+        f(key, type)
+    end
+    return
+end
+
+function _to_string(x::DocType)
+    if x == DOCTYPE_ABSTRACT_TYPE
+        return "abstract type"
+    elseif x == DOCTYPE_CONSTANT
+        return "constant"
+    elseif x == DOCTYPE_FUNCTION
+        return "function"
+    elseif x == DOCTYPE_MACRO
+        return "macro"
+    elseif x == DOCTYPE_MODULE
+        return "module"
+    elseif x == DOCTYPE_STRUCT
+        return "struct"
+    end
+end
+
+function _build_api_page(document::Documenter.Document, config::_Config)
+    subdir = config.subdirectory
+    overview_md = """
+    ```@meta
+    CurrentModule = MathOptInterface
+    DocTestSetup = quote
+        import MathOptInterface as MOI
+    end
+    DocTestFilters = [r"MathOptInterface|MOI"]
+    EditURL = nothing
+    ```
+
+    # [$(config.current_module)](@id DocumenterReference_$(config.current_module))
+
+    This page lists the public API of `$(config.current_module)`.
+
+    !!! info
+        This page is an unstructured list of the $(config.current_module) API. For a
+        more structured overview, read the Manual or Tutorial parts of this
+        documentation.
+
+    Because we use names similar to `Base` like `get` and `set`, MathOptInterface
+    intentionally does not `export` the public API. Instead, to use MOI, import it
+    as follows:
+    ```julia
+    import MathOptInterface as MOI
+    ```
+    """
+    list_of_docstrings = String[]
+    _iterate_over_symbols(config) do key, type
+        if type == DOCTYPE_MODULE
+            return
+        end
+        push!(
+            list_of_docstrings,
+            "## `$key`\n\n```@docs\n$(config.current_module).$key\n```\n\n",
+        )
+        return
+    end
+    md_page = Markdown.parse(overview_md * join(list_of_docstrings, "\n"))
+    filename = "$subdir/$(config.current_module).md"
+    document.blueprint.pages[filename] = Documenter.Page(
+        joinpath(document.user.source, filename),
+        joinpath(document.user.build, filename),
+        document.user.build,
+        md_page.content,
+        Documenter.Globals(),
+        convert(MarkdownAST.Node, md_page),
+    )
+    return
+end
+
+function Documenter.Selectors.runner(
+    ::Type{APIBuilder},
+    document::Documenter.Document,
+)
+    @info "APIBuilder: creating API reference"
+    for config in CONFIG
+        _build_api_page(document, config)
+    end
+    return
+end
+
+end  # module

docs/Project.toml

@@ -2,6 +2,7 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JSONSchema = "7d188eb4-7ad8-530c-ae41-71a32a6d4692"
+MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 
 [compat]

docs/make.jl

@@ -16,6 +16,45 @@ const _IS_GITHUB_ACTIONS = get(ENV, "GITHUB_ACTIONS", "false") == "true"
 # Pass --pdf to build the PDF. On GitHub actions, we always build the PDF.
 const _PDF = findfirst(isequal("--pdf"), ARGS) !== nothing || _IS_GITHUB_ACTIONS
 
+# ==============================================================================
+#  API
+# ==============================================================================
+
+include(joinpath(@__DIR__, "DocumenterReference.jl"))
+empty!(DocumenterReference.CONFIG)
+
+api_reference = DocumenterReference.automatic_reference_documentation(;
+    subdirectory = "api",
+    modules = [MathOptInterface],
+    filter = (name::Symbol) -> begin
+        if name in [
+            :AnyAttribute,
+            :FunctionTypeMismatch,
+            :Index,
+            :SetTypeMismatch,
+            :correct_throw_add_constraint_error_fallback,
+            :dict_compare,
+            :eval,
+            :fix_message,
+            :func_type,
+            :get_fallback,
+            :include,
+            :precompile_constraint,
+            :precompile_model,
+            :precompile_variables,
+            :set_type,
+            :sum_dict,
+            :supports_fallback,
+            :throw_add_constraint_error_fallback,
+            :throw_modify_not_allowed,
+            :throw_set_error_fallback,
+        ]
+            return false
+        end
+        return !any(k -> startswith("$name", k), ["#", "_", "@_"])
+    end,
+)
+
 # ==============================================================================
 #  Documentation structure
 # ==============================================================================
@@ -43,16 +82,7 @@ const _PAGES = [
         "background/infeasibility_certificates.md",
         "background/naming_conventions.md",
     ],
-    "API Reference" => [
-        "reference/standard_form.md",
-        "reference/models.md",
-        "reference/variables.md",
-        "reference/constraints.md",
-        "reference/modification.md",
-        "reference/nonlinear.md",
-        "reference/callbacks.md",
-        "reference/errors.md",
-    ],
+    api_reference,
     "Submodules" => [
         "Benchmarks" => [
             "Overview" => "submodules/Benchmarks/overview.md",
@@ -147,8 +177,7 @@ Documenter.DocMeta.setdocmeta!(
         size_threshold_ignore = [
             "changelog.md",
             "release_notes.md",
-            "reference/models.md",
-            "reference/standard_form.md",
+            "api/MathOptInterface.md",
             "submodules/Bridges/list_of_bridges.md",
             "submodules/Bridges/reference.md",
             "submodules/Utilities/reference.md",
@@ -164,6 +193,7 @@ Documenter.DocMeta.setdocmeta!(
         "https://arxiv.org/abs/2002.03447",
         # https://github.com/JuliaDocs/Documenter.jl/issues/2834
         "https://lpsolve.sourceforge.net/5.5/CPLEX-format.htm",
+        "https://www.fico.com/fico-xpress-optimization/docs/dms2021-01/solver/optimizer/HTML/chapter10_sec_section102.html",
     ],
     modules = [MathOptInterface],
     checkdocs = :exports,