From 9b8a31155847e555bbbf80091db7b7bf1bc6153f Mon Sep 17 00:00:00 2001
From: Florian Spreckelsen <f.spreckelsen@indiscale.com>
Date: Thu, 5 Aug 2021 08:06:21 +0000
Subject: [PATCH] DOC: Add sections to documentation
---
README_SETUP.md | 20 ++++++++++++++++++++
docs/make.jl | 13 ++++++++++++-
docs/src/README_SETUP.md | 1 +
docs/src/api.md | 20 ++++++++++++++++++++
docs/src/assets/logo.svg | 1 +
docs/src/examples.md | 29 +++++++++++++++++++++++++++++
docs/src/index.md | 22 ++++++++--------------
src/CaosDB.jl | 2 ++
8 files changed, 93 insertions(+), 15 deletions(-)
create mode 120000 docs/src/README_SETUP.md
create mode 100644 docs/src/api.md
create mode 100644 docs/src/assets/logo.svg
create mode 100644 docs/src/examples.md
diff --git a/README_SETUP.md b/README_SETUP.md
index c54effe..8010511 100644
--- a/README_SETUP.md
+++ b/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
diff --git a/docs/make.jl b/docs/make.jl
index bfd6289..7edde8b 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,3 +1,14 @@
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}",
+)
diff --git a/docs/src/README_SETUP.md b/docs/src/README_SETUP.md
new file mode 120000
index 0000000..88332e3
--- /dev/null
+++ b/docs/src/README_SETUP.md
@@ -0,0 +1 @@
+../../README_SETUP.md
\ No newline at end of file
diff --git a/docs/src/api.md b/docs/src/api.md
new file mode 100644
index 0000000..14cdb0c
--- /dev/null
+++ b/docs/src/api.md
@@ -0,0 +1,20 @@
+# 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
+```
diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg
new file mode 100644
index 0000000..f9c5005
--- /dev/null
+++ b/docs/src/assets/logo.svg
@@ -0,0 +1 @@
+<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
diff --git a/docs/src/examples.md b/docs/src/examples.md
new file mode 100644
index 0000000..248fb1a
--- /dev/null
+++ b/docs/src/examples.md
@@ -0,0 +1,29 @@
+# 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
diff --git a/docs/src/index.md b/docs/src/index.md
index 2683905..86894e4 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,19 +1,13 @@
# 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"]
```
diff --git a/src/CaosDB.jl b/src/CaosDB.jl
index f9c2557..9064000 100644
--- a/src/CaosDB.jl
+++ b/src/CaosDB.jl
@@ -118,6 +118,8 @@ end # Info
module Utility
+export get_env_var
+
using ..CaosDB
"""
--
GitLab