Update Docs

docs/src/manual/1-start.md

@@ -2,29 +2,7 @@
 
 ## Introduction
 
-This manual aims to explain the fundamental concepts behind loading, manipulating and analyzing models with QUBOTools.
-
-## Quick Start Guide
-
-```@example quick-start
-using QUBOTools
-
-path = joinpath(@__DIR__, "data", "problem.json")
-```
-
-### Reading a Model
-
-```@example quick-start
-model = QUBOTools.read_model(path)
-```
-
-### Visualization
-
-```@example quick-start
-using Plots
-
-plot(QUBOTools.ModelDensityPlot(model))
-```
+This manual aims to explain the fundamental concepts behind loading, manipulating and analyzing models with [QUBOTools](https://github.com/psrenergy/QUBOTools.jl).
 
 ## Table of Contents
 

docs/src/manual/3-usage.md

@@ -6,9 +6,9 @@ using QUBOTools
 
 By loading the package with the `using` statement, only a few constants will be dumped in the namespace, most of them model types.
 
-## Basic File I/O
+## File I/O
 
-To read and write QUBO models one is expected to use the `Base.read`/`Base.write` API.
+To read and write models one should use the [`QUBOTools.read_model`](@ref)/[`QUBOTools.write_model`](@ref) API.
 
 ```@example manual
 # File Path
@@ -20,6 +20,7 @@ model = QUBOTools.read_model(path)
 !!! info
     The [`QUBOTools.read_model`](@ref) and [`QUBOTools.write_model`](@ref) methods will try to infer the file format from the file extension.
     The format can be manually set by passing an extra optional parameter after the source path.
+    For more information, see [File Formats](@ref).
 
 ## Data Access
 
@@ -35,6 +36,12 @@ QUBOTools.linear_terms(model) |> collect
 QUBOTools.quadratic_terms(model) |> collect
 ```
 
+### Model Analysis
+
+```@example manual
+QUBOTools.density(model)
+```
+
 ## File formats
 
 ### Conversion between formats

docs/src/manual/5-formats.md

@@ -1,4 +1,4 @@
-# Formats
+# File Formats
 
 |              Format              | Read  | Write | Model | Solutions | Start | Metadata |
 | :------------------------------: | :---: | :---: | :---: | :-------: | :---: | :------: |
@@ -9,7 +9,7 @@
 
 ## Defining a Custom File Format
 
-```@example file-format
+```@example custom-file-format
 using QUBOTools
 
 struct SuperFormat <: QUBOTools.AbstractFormat
@@ -18,3 +18,57 @@ struct SuperFormat <: QUBOTools.AbstractFormat
     SuperFormat(super::Bool = true) = new(super)
 end
 ```
+
+### Writing Models
+
+To write a model using `SuperFormat`, one must implement the
+
+```julia
+QUBOTools.write_model(io::IO, ::QUBOTools.AbstractModel{V,T,U}, ::SuperFormat) where {V,T,U}
+```
+
+method for the custom format.
+
+!!! info
+    This assumption is valid for text-based and binary formats.
+    If you pretend to write in a format that does not rely on `io::IO` (such as [`QUBOTools.QUBin`](@ref)),
+    you should also implement
+
+    ```julia
+    QUBOTools.write_model(filepath::AbstractString, ::QUBOTools.AbstractModel{V,T,U}, ::SuperFormat) where {V,T,U}
+    ```
+
+```@example custom-file-format
+function QUBOTools.write_model(io::IO, model::QUBOTools.AbstractModel, fmt::SuperFormat)
+    if fmt.super
+        println(io, "Format Type: SUPER")
+
+        _write_super_model(io, model)
+    else
+        println(io, "Format Type: Regular")
+
+        _write_regular_model(io, model)
+    end
+    
+    return nothing
+end
+```
+
+### Reading Models
+
+```@example custom-file-format
+function QUBOTools.read_model(io::IO, fmt::SuperFormat)
+    header = readline(io)
+
+    if fmt.super
+        @assert("SUPER" in header, "Invalid header: '$header' is not SUPER!")
+
+        return _read_super_model(io)
+    else
+        return _read_regular_model(io)
+    end
+end
+```
+
+!!! info
+    [`QUBOTools.read_model`](@ref) should return a [`QUBOTools.Model`](@ref) instance.