Merge branch 'f-consolidate-docs' into 'dev'

DOC: Add sections to documentation

See merge request !6

README_SETUP.md

@@ -44,6 +44,26 @@ julia> ]activate "/path/to/caosdb-julialib"
 julia> ]test
 ```
 
+## Code styling
+
+We use
+[JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) for
+automatic code formatting.  Simply install JuliaFormatter by
+
+```julia-repl
+julia> ]add JuliaFormatter
+```
+
+and execute
+
+```sh
+julia -e 'using JuliaFormatter; format(".", verbose=true)'
+```
+
+in the root directory of caosdb-julialib. You may leave out the
+`verbose=true` option if you do not wish to see which files were
+formatted.
+
 ## Documentation
 
 The documentation can be built locally using

docs/make.jl

 using Documenter, CaosDB
 
-makedocs(modules = [CaosDB], sitename = "CaosDB.jl Documentation")
+makedocs(
+    modules = [CaosDB],
+    sitename = "CaosDB.jl",
+    format = Documenter.HTML(prettyurls = false),
+    pages = [
+        "Home" => "index.md",
+        "Getting started" => "README_SETUP.md",
+        "examples.md",
+        "Library" => "api.md",
+    ],
+    repo = "https://gitlab.com/caosdb/caosdb-julialib/blob/{commit}{path}#{line}",
+)

docs/src/README_SETUP.md

+../../README_SETUP.md
\ No newline at end of file

docs/src/api.md

+# CaosDB.jl's API
+
+Below you find the explicit documentation of CaosDB's public
+interface. You also find the documentation of the internal API which
+is meant for expert use only. Only use those if you know what you're
+doing.
+
+## Public API
+
+```@autodocs
+Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity]
+Private=false
+```
+
+## Expert-use only API functions
+
+```@autodocs
+Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity]
+Public=false
+```

docs/src/assets/logo.svg

+<svg id="svg865" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 124.63 117.57"><defs><style>.cls-1,.cls-3{fill:#fff;}.cls-1,.cls-2,.cls-3{stroke:#0a8791;}.cls-1,.cls-2{stroke-miterlimit:2.41;stroke-width:2.58px;}.cls-2{fill:#0a8791;}.cls-3{stroke-miterlimit:2.41;stroke-width:2.58px;}</style></defs><g id="layer1"><g id="g926"><ellipse id="ellipse917" class="cls-1" cx="75.88" cy="92.55" rx="47.46" ry="23.73"/><ellipse id="ellipse920" class="cls-1" cx="75.88" cy="72.26" rx="47.46" ry="23.73"/><ellipse id="ellipse922" class="cls-2" cx="48.75" cy="50.9" rx="47.46" ry="23.73"/><ellipse id="ellipse924" class="cls-3" cx="85.19" cy="36.85" rx="23.73" ry="47.46" transform="translate(19.98 100.41) rotate(-75.49)"/></g></g></svg>
\ No newline at end of file

docs/src/examples.md

+# Examples
+
+**TODO** Fill the sections below once the parts have been implemented.
+
+## Connect to a CaosDB server
+
+See also the hints on the [Installation](@ref) and set-up of
+CaosDB.jl. CaosDB.jl makes use of the C++ client of CaosDB, so in
+order to connect to a CaosDB server you first have to configure the
+connection via a configuration file as explained in the [documentation
+of CaosDB's C++
+client](https://docs.indiscale.com/caosdb-cpplib). Once the
+configuration is set up, connecting to the server is as easy as
+
+```julia
+using CaosDB
+connection = CaosDB.Connection.connect()
+```
+
+which will establish a connection and print the version of the server
+you are connected to.
+
+## Retrieve a Record
+
+## Execute queries
+
+## Insert, update, and delete entities
+
+## Download a file

docs/src/index.md

 # CaosDB.jl documentation
 
-This will be the index of the documentation of the CaosDB Julia client
-library.
+Welcome to CaosDB.jl, the Julia Client for
+[CaosDB](https://caosdb.org), the opensource research data management
+system. In here you find instruction on how to [Set-up
+CaosDB.jl](@ref), some introductory [Examples](@ref), and an overview
+of [CaosDB.jl's API](@ref).
 
-Manually add a docstring here:
+## Contents
 
-```@docs
-CaosDB.Utility.get_env_var(::AbstractString, ::AbstractString)
-```
-
-
-## Semi-auomatic generation of documentation
-
-Similar to autodoc:
-
-```@autodocs
-Modules=[CaosDB]
+```@contents
+Pages = ["README_SETUP.md", "examples.md", "api.md"]
 ```

src/CaosDB.jl

@@ -118,6 +118,8 @@ end # Info
 
 module Utility
 
+export get_env_var
+
 using ..CaosDB
 
 """