Added documentation

.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Documentation
+
+on: [push, pull_request]
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: "Set up Julia"
+ uses: julia-actions/setup-julia@latest
+ with:
+ version: '1.4'
+ - name: "Install Julia dependencies"
+ run: julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+ - name: "Build and deploy docs"
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: julia --project=docs docs/make.jl

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+XDGSpec = "fe33d248-b583-4bd1-8106-a6949c99f4d9"

docs/make.jl

@@ -0,0 +1,24 @@
+using Documenter
+
+@info "Loading XDGSpec"
+using XDGSpec, XDGSpec.BaseDirectory
+
+@info "Building Documenter.jl docs"
+makedocs(
+ modules = [XDGSpec],
+ format = Documenter.HTML(),
+ sitename = "XDGSpec.jl",
+ doctest = false,
+ checkdocs = :none,
+ pages = Any[
+ "XDGSpec.jl" => "index.md",
+ "Base Directories" => "BaseDirectory.md"
+ ]
+)
+
+@info "Deploying docs"
+deploydocs(
+ target = "build",
+ repo = "github.com/mehalter/XDGSpec.jl.git",
+ branch = "gh-pages"
+)

docs/src/BaseDirectory.md

@@ -0,0 +1,42 @@
+# Base Directories
+
+```@meta
+CurrentModule = XDGSpec.BaseDirectory
+```
+
+The [XDG Base Directory
+Speicification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+provides standard locations to store application data, configuration, and cached
+data.
+
+## Data directories
+
+```@docs
+save_data_path
+load_data_paths
+xdg_data_home
+xdg_data_dirs
+```
+
+## Configuration directories
+
+```@docs
+save_config_path
+load_config_paths
+load_first_config
+xdg_config_home
+xdg_config_dirs
+```
+
+## Cache directory
+
+```@docs
+save_cache_path
+xdg_cache_home
+```
+
+## Runtime directory
+
+```@docs
+get_runtime_dir
+```

docs/src/index.md

@@ -0,0 +1,16 @@
+# XDGSpec.jl
+
+```@meta
+CurrentModule = XDGSpec
+```
+
+`XDGSpec.jl` is a Julia library supporting various freedesktop standards.
+
+## Table of Contents
+
+```@contents
+Pages = [
+ "BaseDirectory.md",
+ ]
+Depth = 2
+```

src/BaseDirectory.jl

@@ -13,16 +13,30 @@ export xdg_data_home, xdg_data_dirs, xdg_config_home, xdg_config_dirs,
  xdg_cache_home, save_config_path, save_data_path, save_cache_path,
  load_config_paths, load_data_paths, get_runtime_dir
 
+"""
+`\$XDG_DATA_HOME` or the default, `~/.local/share`
+"""
 xdg_data_home = get(ENV, "XDG_DATA_HOME", joinpath(Sys.homedir(), ".local", "share"))
 
+"""
+A list of directory paths in which application data may be stored, in preference order.
+"""
 xdg_data_dirs = [xdg_data_home;
  filter(!isempty, split(get(ENV, "XDG_DATA_DIRS", "/usr/local/share:/usr/share"), ":"))]
-
+"""
+`\$XDG_CONFIG_HOME` or the default, `~/.config`
+"""
 xdg_config_home = get(ENV, "XDG_CONFIG_HOME", joinpath(Sys.homedir(), ".config"))
 
+"""
+A list of directory paths in which configuration may be stored, in preference order.
+"""
 xdg_config_dirs = [xdg_config_home;
  filter(!isempty, split(get(ENV, "XDG_CONFIG_DIRS", "/etc/xdg"), ":"))]
 
+"""
+`\$XDG_CACHE_HOME` or the default, `~/.cache`
+"""
 xdg_cache_home = get(ENV, "XDG_CACHE_HOME", joinpath(Sys.homedir(), ".cache"))
 
 """
@@ -91,6 +105,11 @@ take precedence over later ones, and the user-specific config dir comes first.
 """
 load_config_paths(resource...) = load_paths(xdg_config_dirs, resource...)
 
+"""
+ function load_first_config(resource...)
+
+Returns the first result from load_config_paths, or None if there is nothing to load.
+"""
 function load_first_config(resource...)
  for config in load_config_paths(resource...)
  return config