From 1dd48e703e5ef5a24188d4b265386525ad1b3f26 Mon Sep 17 00:00:00 2001 From: Wataru Otsubo Date: Sat, 14 Sep 2024 23:48:15 +0900 Subject: [PATCH] add: docs (mainly docstrings) --- docs/make.jl | 5 +- docs/src/about_software.md | 27 ++++++++-- src/import_data.jl | 95 ++++++++++++++++++++++++++++++++++-- src/parse_qaqc_master_log.jl | 5 ++ test/runtests.jl | 2 +- 5 files changed, 126 insertions(+), 8 deletions(-) diff --git a/docs/make.jl b/docs/make.jl index 61d00ff..94c9851 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -8,7 +8,10 @@ DocMeta.setdocmeta!( recursive = true, ) -links = InterLinks("DataFrames" => "https://dataframes.juliadata.org/dev/objects.inv") +links = InterLinks( + "DataFrames" => "https://dataframes.juliadata.org/dev/objects.inv", + "Dates" => "https://docs.julialang.org/en/v1/objects.inv", +) makedocs( modules = [PSBoardDataBase], diff --git a/docs/src/about_software.md b/docs/src/about_software.md index cbcbeaf..49742fc 100644 --- a/docs/src/about_software.md +++ b/docs/src/about_software.md @@ -6,14 +6,35 @@ CurrentModule = PSBoardDataBase このリポジトリにあるのは、JATHub masterのログファイル、及びGoogle SheetsからエクスポートしたCSVファイルからデータベースを作成するためのコードである。 メインの関数は[`create_database_from_exported_csvs`](@ref)である。 -## テストについて +## 動かし方 +[Julia](https://julialang.org)は[juliaup](https://github.com/JuliaLang/juliaup)でインストールする。 +リポジトリのルート(`Project.toml`がある)で +``` +$ julia --project +``` +をするとJuliaのREPLが立ち上がる。 + +`]`をおして`Pkg`モードに入り、`instantiate`を実行すると、必要なパッケージを自動でインストールする。 + +backspaceでjulianモードに戻り(左側が`julia>`になってる)、`using PSBoardDataBase`をすると使えるようになる。 + +`?`を押すとhelpモードに入り、関数名などをいれるとそのドキュメント(下にあるものと同じ)が閲覧できる。 + +`PSBoardDataBase.create_database_from_exported_csvs`を検索すると使い方がわかる。 + +# テストについて テストでは実際にデータベースを作成している。 デフォルトでは全部は実行しないが、master log fileをおき、かつ環境変数`LOCAL_TEST`を設定することで、master log fileが必要な工程まで含めて実行できる。[^1] [^1]: master log fileはgitには入れたくないので、このような形態をとっている。 -## API +# 新しいQAQCキャンペーン時に更新すべき内容 + +- [`PSBoardDataBase.insert_qaqc_campaign_id`](@ref): キャンペーンの日時 +- [`PSBoardDataBase.get_campaign_id_from_run_id`](@ref): runidとの関係 + +# API ```@index ``` @@ -22,7 +43,7 @@ CurrentModule = PSBoardDataBase Modules = [PSBoardDataBase] ``` -### `QaqcMasterLog` +## `QaqcMasterLog` ```@autodocs Modules = [QaqcMasterLog] diff --git a/src/import_data.jl b/src/import_data.jl index 2d44e26..596a17b 100644 --- a/src/import_data.jl +++ b/src/import_data.jl @@ -1,3 +1,8 @@ +""" + insert_qaqc_campaign_id(db::SQLite.DB) + +Fill qaqc_campaigns table in `db`. +""" function insert_qaqc_campaign_id(db::SQLite.DB) campaigns = [1, 2, 3] dates = [ @@ -22,6 +27,11 @@ function insert_qaqc_campaign_id(db::SQLite.DB) nothing end +""" + insert_qaqc_positions(db::SQLite.DB) + +Fill qaqc_positions table in `db`. +""" function insert_qaqc_positions(db::SQLite.DB) stmt = DBInterface.prepare( db, @@ -49,7 +59,12 @@ function insert_qaqc_positions(db::SQLite.DB) end """ + prepare_single_result_df(single_result_table::DataFrame) + Common preprocess(format) function for single result table. + +# Detail +- convert `timestamp` to [`DateTime`](@extref Dates.DateTime) """ function prepare_single_result_df(single_result_table::DataFrame) df = copy(single_result_table, copycols = true) @@ -66,6 +81,8 @@ function prepare_single_result_df(single_result_table::DataFrame) end """ + prepare_runlist_df(runlist_table::DataFrame) + Common preprocess(format) function for runlist table. """ function prepare_runlist_df(runlist_table::DataFrame) @@ -73,7 +90,10 @@ function prepare_runlist_df(runlist_table::DataFrame) end """ + add_psboard_ids(db::SQLite.DB, single_result_table::DataFrame) + Add PS Board IDs from single test result table. +Assume that all PS Boards are included in `single_result_table`. """ function add_psboard_ids(db::SQLite.DB, single_result_table::DataFrame) df = combine(groupby(single_result_table, :motherboard_id)) do df @@ -98,7 +118,12 @@ function add_psboard_ids(db::SQLite.DB, single_result_table::DataFrame) nothing end -function add_qaqc_runlist(db::SQLite.DB, runlist_table::DataFrame) +""" + add_qaqc_runlist_from_runlist(db::SQLite.DB, runlist_table::DataFrame) + +Add QAQC runs to `qaqc_runs` table in `db` from RUNLIST csv. +""" +function add_qaqc_runlist_from_runlist(db::SQLite.DB, runlist_table::DataFrame) stmt_insert_runid = DBInterface.prepare( db, sql""" @@ -130,16 +155,34 @@ function add_qaqc_runlist(db::SQLite.DB, runlist_table::DataFrame) nothing end +""" + get_campaign_id_from_run_id(runid::Integer) +""" function get_campaign_id_from_run_id(runid::Integer) if runid < 63 1 elseif runid < 98 2 - else + elseif runid < 169 3 + else + @error "Fix this function" + DomainError("runid $(runid) is not registered to the software") end end +""" + add_qaqc_single_result( + db::SQLite.DB, + single_result_table::DataFrame, + runlist_table::DataFrame, + ) -> nothing + +Fill `qaqc_single_run_results` in `db` from single result table DataFrame. +Additionaly, it +1. automatically add `runid` if it's not in `qaqc_runs` table in `db`. +2. automatically update fields in `qaqc_runs` table. +""" function add_qaqc_single_result( db::SQLite.DB, single_result_table::DataFrame, @@ -303,6 +346,12 @@ function add_qaqc_single_result( nothing end +""" + prepare_dispatch_table(raw_dispatch_table::DataFrame)::DataFrame + +Format `qaqc_dispatch` DataFrame from exported CSV. +Used in [`add_qaqc_dispatch`](@ref). +""" function prepare_dispatch_table(raw_dispatch_table::DataFrame)::DataFrame df = copy(raw_dispatch_table, copycols = true) transform!( @@ -334,6 +383,11 @@ function prepare_dispatch_table(raw_dispatch_table::DataFrame)::DataFrame df end +""" + add_qaqc_dispatch(db::SQLite.DB, dispatch_table::DataFrame) + +Fill `qaqc_dispatch` table in `db` from `dispatch_table`. +""" function add_qaqc_dispatch(db::SQLite.DB, dispatch_table::DataFrame) dispatch_table = prepare_dispatch_table(dispatch_table) @@ -355,6 +409,8 @@ function add_qaqc_dispatch(db::SQLite.DB, dispatch_table::DataFrame) end """ + add_qaqc_runlist_from_masterlogs(db::SQLite.DB, logs_dir::AbstractString) -> nothing + Add qaqc run list from master log files in `logs_dir`. Currently, it adds long runs and run with id 20-23 only (since normal runs are added from single run results table). """ @@ -439,6 +495,18 @@ function add_qaqc_runlist_from_masterlogs(db::SQLite.DB, logs_dir::AbstractStrin nothing end +""" + prepare_100test_table(table::DataFrame)::DataFrame + +Format 100test result `table` from exported CSV. +Used in [`add_qaqc_100test_result`](@ref). + +# Detail +- Format `motherboard ID`s + - `PS00xxxx` -> `Int64(xxxx)` + - `xxxx` -> `Int64(xxxx)` +- For `psbid == 484` and `runid == 115` results, make all result fields to `missing` since they contain abnormal strings. +""" function prepare_100test_table(table::DataFrame)::DataFrame df = copy(table, copycols = true) @@ -464,6 +532,18 @@ function prepare_100test_table(table::DataFrame)::DataFrame df end +""" + get_num_tests_for_extra_runs(runid::Int64) + +Get number of tests for extra QAQC runs. +They are usually 100. + +Current abnormal runs: + +| runid | # of runs | +|-------|-----------| +| 99| 246| +""" function get_num_tests_for_extra_runs(runid::Int64) if runid == 99 246 @@ -472,6 +552,15 @@ function get_num_tests_for_extra_runs(runid::Int64) end end +""" + add_qaqc_100test_result(db::SQLite.DB, table::DataFrame) -> nothing + +Fill `qaqc_extra_run_results` table in `db` from `table` DataFrame, +which is converted from a raw exported CSV. + +# Detail +- skips psboards in `resistance_test_passed` with `passed == false` +""" function add_qaqc_100test_result(db::SQLite.DB, table::DataFrame) position_id_map = ["B-$i-$j" for i in 0:1 for j in 1:9] |> enumerate .|> (x -> begin @@ -543,7 +632,6 @@ function add_qaqc_100test_result(db::SQLite.DB, table::DataFrame) ) for row in eachrow(table) - # TODO: get runid from master log file if DBInterface.execute(stmt_search_runid, (; runid = row.runid)) |> isempty # search for resistance error if !isempty( @@ -554,6 +642,7 @@ function add_qaqc_100test_result(db::SQLite.DB, table::DataFrame) ) continue end + error("Runid $(row.runid) not found in `qaqc_runs` table.") end DBInterface.execute( diff --git a/src/parse_qaqc_master_log.jl b/src/parse_qaqc_master_log.jl index 2b94bf5..12429d4 100644 --- a/src/parse_qaqc_master_log.jl +++ b/src/parse_qaqc_master_log.jl @@ -1,3 +1,6 @@ +""" +Module for QAQC master log parser. +""" module QaqcMasterLog using Dates @@ -19,6 +22,8 @@ struct QaqcMasterLogMetadata end """ + parse_master_log(logfile::AbstractString) + Parse master log. If the `logfile` is empty, return `nothing`. """ diff --git a/test/runtests.jl b/test/runtests.jl index 85205cb..72a8a70 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -42,7 +42,7 @@ true || include("../src/PSBoardDataBase.jl") runlist_table = CSV.read("input/PS board QAQC Data Base - RUNLIST.csv", DataFrame) @test PSBoardDataBase.add_psboard_ids(db, single_result_df) |> isnothing - @test PSBoardDataBase.add_qaqc_runlist(db, runlist_table) |> isnothing + @test PSBoardDataBase.add_qaqc_runlist_from_runlist(db, runlist_table) |> isnothing @test PSBoardDataBase.add_qaqc_single_result(db, single_result_df, runlist_table) |> isnothing