diff --git a/README_SETUP.md b/README_SETUP.md index c54effee4dfd9dfa569a4162013c77c883ec1121..801051111ad455b9b357bcfd51d936881e7dcb3a 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 bfd62893e9e67c339b8f0dadefc62914d25ac42c..7edde8b94abb69822575cefae2b1c144b8acce30 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 0000000000000000000000000000000000000000..88332e357f5e06f3de522768ccdcd9e513c15f62 --- /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 0000000000000000000000000000000000000000..14cdb0cca131652c8f5b8ceeeb20edc3377a174a --- /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 0000000000000000000000000000000000000000..f9c500506cf403da71393c756d10a09a1dcd9cd2 --- /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 0000000000000000000000000000000000000000..248fb1ac5fce9af3ec103fd7eed508ecfd5afcc4 --- /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 2683905a8f4c1cae89d875e57db30cde0afcbd3a..86894e45d5367de225b2ae4bb959e9a5214fa89b 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 f9c255790ec5c2c202caa611c09d09be207850bb..906400025ea1e789254dcb8539c1600be3aebf1a 100644 --- a/src/CaosDB.jl +++ b/src/CaosDB.jl @@ -118,6 +118,8 @@ end # Info module Utility +export get_env_var + using ..CaosDB """