Merge pull request #15 from Herb-AI/add_linting

Add linting, doctests

.JuliaFormatter.toml

@@ -0,0 +1 @@
+style = "sciml"

.dev/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Git = "d7ba0133-e1db-5d97-8f8c-041e4b3a1eb2"
+JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"

.dev/herb_format.jl

@@ -0,0 +1,75 @@
+"""
+Formatting script inspired by that of the `Flux.jl` package, which
+can be found at:
+
+https://github.com/FluxML/Flux.jl/blob/caa1ceef9cf59bd817b7bf5c94d0ffbec5a0f32c/dev/flux_format.jl
+"""
+
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+using JuliaFormatter
+
+help = """
+Usage: herb_format [flags] [FILE/PATH]...
+
+Formats the given julia files using the Herb formatting options.
+If paths are given instead, it will format all *.jl files under
+the paths. If nothing is given, all changed julia files are formatted.
+
+    -v, --verbose
+        Print the name of the files being formatted with relevant details.
+
+    -h, --help
+        Print this help message.
+
+    --check
+        Check if the files are formatted without changing them.
+"""
+
+options = Dict{Symbol, Bool}()
+indices_to_remove = []      # used to delete options once processed
+
+for (index, arg) in enumerate(ARGS)
+    if arg[1] != '-'
+        continue
+    end
+    val = true
+    if arg in ["-v", "--verbose"]
+        opt = :verbose
+        push!(indices_to_remove, index)
+    elseif arg in ["-h", "--help"]
+        opt = :help
+        push!(indices_to_remove, index)
+    elseif arg == "--check"
+        opt = :overwrite
+        val = false
+        write(stdout, "Checking files.\n")
+        push!(indices_to_remove, index)
+    else
+        error("Option $arg is not supported.")
+    end
+    options[opt] = val
+end
+
+# remove options from args
+deleteat!(ARGS, indices_to_remove)
+
+# print help message if asked
+if haskey(options, :help)
+    write(stdout, help)
+    exit(0)
+end
+
+# otherwise format files
+if isempty(ARGS)
+    filenames = readlines(`git ls-files "*.jl"`)
+else
+    filenames = ARGS
+end
+
+write(stdout, "Formatting in progress.\n")
+# format returns true if the files were already formatted
+# and false if they were not (had to be formatted)
+exit(format(filenames; options...) ? 0 : 1)

.dev/setup.jl

@@ -0,0 +1,21 @@
+"""
+Dev environment setup script inspired by that of the `Flux.jl` package, which
+can be found at:
+
+https://github.com/FluxML/Flux.jl/blob/caa1ceef9cf59bd817b7bf5c94d0ffbec5a0f32c/dev/setup.jl
+"""
+
+# instantiate the environment
+using Pkg
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+
+# setup the custom git hook
+using Git
+
+# set the local hooks path
+const git = Git.git()
+run(`$git config --local core.hooksPath .githooks/`)
+
+# set file permission for hook
+Base.Filesystem.chmod(".githooks", 0o777; recursive = true)

.githooks/pre-commit

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# Get the list of files that are about to be committed and filter out only the .jl files
+files=$(git diff --cached --name-only --diff-filter=ACM | grep "\.jl$")
+
+# If no files are found, exit
+if [ -z "$files" ]; then
+    exit 0
+fi
+
+# Run the herb formatter on the list of files
+julia --startup-file=no -O1 --color=yes .dev/herb_format.jl --check $files
+
+# If the formatter exited with an error, abort the commit
+if [ $? -ne 0 ]; then
+    echo "Error: formatter must be run on the files before committing."
+    echo "Please run julia .dev/herb_format.jl YOUR_CHANGED_FILES.jl"
+    exit 1
+fi

.github/workflows/JuliaFormatter.yml

@@ -0,0 +1,54 @@
+name: Formatting Check
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  format:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            julia_file_change:
+              - added|modified: '**.jl'
+          list-files: 'shell'
+
+      - uses: julia-actions/setup-julia@latest
+        if: steps.filter.outputs.julia_file_change == 'true'
+        with:
+          version: ${{ matrix.version }}
+
+      - uses: julia-actions/cache@v1
+
+      - name: Apply JuliaFormatter
+        if: steps.filter.outputs.julia_file_change == 'true'
+        run: |
+          julia --color=yes .dev/herb_format.jl --verbose ${{ steps.filter.outputs.julia_file_change_files }}
+
+      - name: Check formatting diff
+        if: steps.filter.outputs.julia_file_change == 'true'
+        run: |
+          git diff --color=always --exit-code

.github/workflows/check_docs.yml

@@ -0,0 +1,55 @@
+name: Check Docs
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+jobs:
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Julia
+      uses: julia-actions/setup-julia@v1
+      with:
+        version: '1' # Use the latest stable Julia version
+    - name: Install dependencies
+      run: |
+        julia --project=docs -e '
+          using Pkg;
+          Pkg.develop(PackageSpec(path=pwd()));
+          Pkg.instantiate();
+          Pkg.add("Documenter");
+        '
+    - name: Try building documentation and run doctests
+      run: |
+        julia --project=docs -e '
+          using Documenter, HerbCore;
+          content = """
+            ```@meta
+            CurrentModule = HerbCore
+            DocTestSetup = quote
+                using HerbCore
+            end
+            ```
+
+            ```@autodocs
+            Modules = [HerbCore]
+            ```
+          """
+          mkpath("src/")
+          open("src/index.md", "w") do file
+            write(file, content)
+          end
+          makedocs(
+            sitename="HerbCore.jl",
+            modules=[HerbCore],
+            format=Documenter.HTML(),
+            doctest=true,
+            warnonly=[:missing_docs],
+            pages=["index.md"]
+          );
+        '