Merge pull request #95 from JuliaImages/vs/docs-doctests

docs: doctests, versioning merge, generated wrapped-functions list

Author: ViralBShah

.gitignore

@@ -16,6 +16,8 @@ deps/src/
 # Build artifacts for creating documentation generated by the Documenter package
 docs/build/
 docs/site/
+# generated from gen/funclist.csv by docs/make.jl
+docs/src/wrapped_functions.md
 
 # File generated by Pkg, the package manager, based on a corresponding Project.toml
 # It records a fixed state of all packages used by the project. As such, it should not be

Project.toml

@@ -1,7 +1,7 @@
 name = "OpenCV"
 uuid = "f878e3a2-a245-4720-8660-60795d644f2a"
 authors = ["Archit Rungta <architrungta120@gmail.com>"]
-version = "4.10.0"
+version = "4.9.0"
 
 [deps]
 CxxWrap = "1f15a43c-97ca-5a2a-ae31-89f07a497df4"

docs/make.jl

@@ -4,6 +4,48 @@ using Documenter
 
 DocMeta.setdocmeta!(OpenCV, :DocTestSetup, :(using OpenCV); recursive=true)
 
+# Generate the "Wrapped functions" page from gen/funclist.csv at build time, so the
+# list of wrapped OpenCV APIs in the docs stays in lockstep with the bindings.
+function generate_wrapped_functions_page()
+    csv = joinpath(@__DIR__, "..", "gen", "funclist.csv")
+    out = joinpath(@__DIR__, "src", "wrapped_functions.md")
+    entries = String[]
+    for line in eachline(csv)
+        s = strip(line)
+        (isempty(s) || startswith(s, "#")) && continue
+        startswith(s, "cv.") && push!(entries, String(s[4:end]))
+    end
+    free = sort(unique(filter(e -> !occursin('.', e), entries)))
+    groups = Dict{String, Vector{String}}()
+    for e in filter(e -> occursin('.', e), entries)
+        cls, rest = split(e, '.'; limit = 2)
+        push!(get!(groups, String(cls), String[]), String(rest))
+    end
+    for (k, v) in groups
+        groups[k] = sort(unique(v))
+    end
+    nfuncs = length(free) + sum(length, values(groups); init = 0)
+    open(out, "w") do io
+        println(io, "# Wrapped functions\n")
+        println(io, "!!! note")
+        println(io, "    This page is generated from [`gen/funclist.csv`](https://github.com/JuliaImages/OpenCV.jl/blob/master/gen/funclist.csv) at build time — the authoritative list of every OpenCV function exposed by the bindings ($nfuncs functions).\n")
+        println(io, "Names follow the `cv::` → `OpenCV.` convention (see [Core concepts](@ref)): " *
+                    "free functions map directly (`cv.add` → `OpenCV.add`); class *static* methods " *
+                    "flatten with `_` (`cv.ORB.create` → `OpenCV.ORB_create`); and *instance* methods " *
+                    "dispatch on the object (`cv.FileStorage.open` → `OpenCV.open(fs, …)`). Everything is " *
+                    "reached through the `OpenCV.` prefix.\n")
+        println(io, "## Free functions\n")
+        println(io, join(("`OpenCV.$f`" for f in free), " · "), "\n")
+        println(io, "## Classes and submodules\n")
+        for cls in sort(collect(keys(groups)))
+            println(io, "### `$cls`\n")
+            println(io, join(("`cv.$cls.$m`" for m in sort(groups[cls])), " · "), "\n")
+        end
+    end
+    return out
+end
+generate_wrapped_functions_page()
+
 makedocs(;
     modules=[OpenCV],
     sitename="OpenCV.jl",
@@ -13,6 +55,7 @@ makedocs(;
         "Core concepts" => "core_concepts.md",
         "Reading and Writing of Images" => "Getting started with Images.md",
         "API reference" => "api.md",
+        "Wrapped functions" => "wrapped_functions.md",
     ]
 )
 

docs/src/api.md

@@ -15,9 +15,8 @@ The thousands of *wrapped* OpenCV functions (`imread`, `cvtColor`, `GaussianBlur
 `ORB_create`, …) keep their C++ names with the `cv::` namespace stripped and are
 reached through the `OpenCV.` prefix — e.g. `cv::cvtColor` is `OpenCV.cvtColor` and
 the flag `cv::IMREAD_GRAYSCALE` is `OpenCV.IMREAD_GRAYSCALE`. See
-[Core concepts](@ref) for the naming and data conventions, and the generated
-[`gen/funclist.csv`](https://github.com/JuliaImages/OpenCV.jl/blob/master/gen/funclist.csv)
-for the complete list of wrapped methods.
+[Core concepts](@ref) for the naming and data conventions, and
+[Wrapped functions](@ref) for the complete generated list.
 
 ## Image and array types
 

docs/src/core_concepts.md

@@ -50,10 +50,16 @@ Any `AbstractArray{T,3}` with `T` one of the supported element types is accepted
 wherever an image is expected (this Union is `OpenCV.InputArray`), so you can pass a
 plain Julia array directly and wrap one as a `Mat` with `OpenCV.Mat(A)`:
 
-```julia
-A = rand(UInt8, 3, 640, 480)     # (channels, cols, rows)
-img = OpenCV.Mat(A)              # zero-copy view; shares memory with A
-gray = OpenCV.cvtColor(A, OpenCV.COLOR_BGR2GRAY)   # plain arrays work too
+```jldoctest
+julia> using OpenCV
+
+julia> A = rand(UInt8, 3, 640, 480);          # (channels, cols, rows)
+
+julia> size(OpenCV.Mat(A))                    # zero-copy view; shares memory with A
+(3, 640, 480)
+
+julia> size(OpenCV.cvtColor(A, OpenCV.COLOR_BGR2GRAY))   # plain arrays work too
+(1, 640, 480)
 ```
 
 The supported element types are `UInt8`, `Int8`, `UInt16`, `Int16`, `Int32`,

docs/src/index.md

@@ -18,17 +18,30 @@ extraction, calibration, and much more — backed by the compiled library throug
 This installs the package and the precompiled OpenCV binaries; no system OpenCV is
 required.
 
-## OpenCV version
+## Versioning
 
-This release wraps **OpenCV 4.13.0**, pinned in `gen/OPENCV_VERSION` and provided at
-runtime by `OpenCV_jll` 4.13.x. Query the version and build configuration from Julia:
+```@eval
+using Markdown, OpenCV
+v = OpenCV.getVersionString()
+Markdown.parse(
+    "This release wraps **OpenCV $v**, pinned in " *
+    "[`gen/OPENCV_VERSION`](https://github.com/JuliaImages/OpenCV.jl/blob/master/gen/OPENCV_VERSION) " *
+    "and provided at runtime by `OpenCV_jll`. Query it from Julia with " *
+    "`OpenCV.getVersionString()` (or `OpenCV.getBuildInformation()` for the full " *
+    "build configuration):"
+)
+```
 
-```julia
+```@repl
 using OpenCV
-OpenCV.getVersionString()     # "4.13.0"
-OpenCV.getBuildInformation()  # full build info string
+OpenCV.getVersionString()
 ```
 
+The package version itself tracks the wrapped OpenCV release. Within a given OpenCV
+major/minor line, breaking changes to the *Julia* API are signalled by bumping the
+package's minor version and called out in release notes — they do not require bumping
+the OpenCV major.
+
 ## Quick start
 
 ```julia
@@ -63,23 +76,15 @@ mosaic(img_orig, img_back; nrow=1)
   scalars, and Julia-array interop.
 - [Reading and Writing of Images](@ref) — `imread`/`imwrite` and the FileIO
   `load`/`save` interface, with flags and display.
-- [API reference](@ref) — the hand-written types and I/O helpers. The full list of
-  wrapped OpenCV functions lives in
-  [`gen/funclist.csv`](https://github.com/JuliaImages/OpenCV.jl/blob/master/gen/funclist.csv).
+- [API reference](@ref) — the hand-written types and I/O helpers.
+- [Wrapped functions](@ref) — the complete generated list of wrapped OpenCV functions.
 
 If you are new to OpenCV, the upstream
 [OpenCV tutorials](https://docs.opencv.org/4.x/d9/df8/tutorial_root.html) are the best
 starting point. Function and argument names mirror the C++/Python API, so most
 tutorials translate directly — the Julia-specific pieces are the `Mat`/`Vec` types and
 the array/image interop, all covered in [Core concepts](@ref).
 
-## Versioning
-
-The package version tracks the wrapped OpenCV release (currently `4.13.x` for OpenCV
-4.13.0). Within a given OpenCV major/minor line, breaking changes to the *Julia* API
-are signalled by bumping the package's minor version and called out in release notes —
-they do not require bumping the OpenCV major.
-
 ## Contributing
 
 Issues and pull requests are welcome at the