Add DocInventories.convert function

docs/src/api.md

@@ -13,6 +13,12 @@ using DocInventories: uri, spec
 
 for [`uri`](@ref DocInventories.uri) and [`spec`](@ref DocInventories.spec), or used with the `DocInventories` prefix, e.g., [`DocInventories.save`](@ref).
 
+In typical usage, the following non-exported I/O routines would be commonly used:
+
+* [`DocInventories.save`](@ref)
+* [`DocInventories.convert`](@ref)
+* [`DocInventories.set_metadata`](@ref)
+
 ---
 
 ```@autodocs

src/io.jl

@@ -30,7 +30,7 @@ end
 """Write the [`Inventory`](@ref) to file in the specified format.
 
 ```julia
-save(filename, inventory; mime=auto_mime(filename))
+DocInventories.save(filename, inventory; mime=auto_mime(filename))
 ```
 
 writes `inventory` to `filename` in the specified MIME type. By default, the
@@ -71,3 +71,25 @@ function save(filename::AbstractString, inventory, mime)
         end
     end
 end
+
+
+"""Convert an inventory file.
+
+```julia
+DocInventories.convert("objects.inv", "inventory.toml")
+```
+
+converts the input file `"objects.inv"` in the [Sphinx Inventory Format](@ref)
+to the [TOML Format](@ref) `"inventory.toml"`.
+
+This is a convenience function to simply load an [`Inventory`](@ref) from the
+input file and write it to the output file. Both the input and output file must
+have known file extensions. The `project` and `version` metadata may be given
+as additional keyword arguments to be written to the output file, see
+[`set_metadata`](@ref).
+"""
+function convert(file_in, file_out; kwargs...)
+    inventory = Inventory(file_in; root_url="")
+    inventory = set_metadata(inventory; kwargs...)
+    save(file_out, inventory)
+end

src/metadata.jl

@@ -46,7 +46,7 @@ end
 
 
 function set_metadata(filename::AbstractString, mime; kwargs...)
-    inventory = set_metadata(Inventory(filename; mime, root_url=""); kwargs...)
+    inventory = set_metadata(Inventory(filename; mime=mime, root_url=""); kwargs...)
     save(filename, inventory; mime)
 end
 

test/test_inventory.jl

@@ -111,6 +111,34 @@ end
 end
 
 
+@testset "convert" begin
+    rootname = tempname()
+    inventory_toml = "$rootname.toml"
+    inventory_txt_gz = "$rootname.txt.gz"
+    DocInventories.convert(joinpath(@__DIR__, "quantumpropagators.inv"), inventory_toml)
+    inventory = Inventory(inventory_toml; root_url="")
+    @test inventory.project == "QuantumPropagators.jl"
+    @test inventory.version == "0.7.0+dev"
+    DocInventories.convert(
+        inventory_toml,
+        inventory_toml;
+        project="QuantumPropagators",
+        version="0.7.0",
+    )
+    inventory = Inventory(inventory_toml; root_url="")
+    @test inventory.project == "QuantumPropagators"
+    @test inventory.version == "0.7.0"
+    DocInventories.convert(
+        inventory_toml,
+        inventory_txt_gz;
+        project="QuantumPropagators.jl",
+    )
+    inventory = Inventory(inventory_txt_gz; root_url="")
+    @test inventory.project == "QuantumPropagators.jl"
+    @test inventory.version == "0.7.0"
+end
+
+
 @testset "Read invalid" begin
 
     @test_throws RequestError begin