クイックスタート

リポジトリにある例を試してみたい方へ

まずは動作させてみたいという方は、以下のようにコマンドを実行してください。

$ pip install statements-manager
$ git clone https://github.com/tsutaj/statements-manager.git
$ cd statements-manager

$ ss-manager run ./sample

ss-manager run ./sample を実行した後は、H 問題以外の各問題ディレクトリについて、 ss-out ディレクトリ内に HTML が生成されており、 tests ディレクトリ内に制約ファイルが生成されているはずです。

H 問題の問題文は Google Docs にあるため、この手順だけでは HTML 生成ができません。Google Docs API を使用可能にするで述べられている設定を行うと、H 問題に関しても HTML 生成が可能です。

デフォルトでは HTML が生成されますが、Markdown や PDF の出力にも対応しています。出力形式を指定するには -o, --output オプションを使います。

# generate Markdown files
ss-manager run ./sample -o md

# generate PDF files
ss-manager run ./sample -o pdf

また、 -p, --make-problemset オプションによって、問題セット全体をまとめたファイルの生成も可能です。

# generate problemset PDF
ss-manager run ./sample -o pdf -p

コマンドの詳しい使い方についてはコマンドをご覧ください。

本ツールの導入の流れを知りたい方へ

問題文と設定ファイルを実際に用意して動作させることで、本ツールの導入の流れを説明します。

ここでは、「整数 \(A\) と \(B\) が与えられるので、 \(A + B\) の計算結果を出力してください」という問題を作りたいときに、どのように問題文を準備すればよいか説明します。ファイル構成などの詳細を確認したいときはリポジトリ内のサンプルを参照してください。

問題文を用意する

問題文を普通に書くと、以下のような Markdown ファイル statement.md を作ることになるでしょう。(数式は MathJax を想定した記法になっています)

### Problem Statement

You are given two integers $A$ and $B$. Print the calculation result of $A + B$.

### Input

Input is given from standard input in the following format:

```
$A$ $B$
```

### Output

You have to output the calculation result of $A + B$ to the standard output.

### Constraints

- $1 \leq A, B \leq 10^9$

### Sample Input 1

```
3 5
```

### Sample Output 1

```
8
```

### Sample Input 2

```
10000 100
```

### Sample Output 2

```
10100
```

この Markdown にはいくつか問題点があります。

入力 \(A, B\) に対する制約がファイルに直接書かれています。仮に \(A, B\) の上限をともに \(10^{9}\) から \(10^{18}\) に変更しなければならないとき、問題文の制約とデータセット生成器で使う制約を両方変更しなければなりませんが、これを別々に変更するとミスが起きやすいです。
サンプル入出力も直接書かれているため、上で述べたことと同様の問題が起きやすいです。また、サンプルのナンバリングもファイルに直接書かれているため、番号が重複したり抜け落ちたりする可能性があります。

これらの問題を解消するため、statements-manager を導入して問題文を書き直していきます。

問題制約とサンプル入出力を別ファイルに移す

サンプル入出力を別ファイルに移します。入力例 1 に対応するファイルは 00_sample_00.in に、出力例 1 に対応するファイルは 00_sample_00.out に用意します。同様に入出力例 2 に対応するファイル 00_sample_01.in, 00_sample_01.out も用意します。これらのファイルは全て tests というディレクトリ内に格納しておきます。

また、問題制約を問題文ファイルから分離するため、以下のような設定ファイル problem.toml を用意します。

# problem id (it is used for the name of output html file)
id = "A"

# output params
params_path = "./tests/constraints.hpp"

# path to statements
[[statements]]
path = "./statement.md"
lang = "en"

# write constraints
[constraints]
    MIN_AB = 1
    MAX_AB = 1_000_000_000

これで問題制約とサンプル入出力を問題文から分離できました！最後に、問題文のファイル statement.md を次のように書き換えます。

### Problem Statement

You are given two integers $A$ and $B$. Print the calculation result of $A + B$.

### Input

Input is given from standard input in the following format:

```
$A$ $B$
```

### Output

You have to output the calculation result of $A + B$ to the standard output.

### Constraints

- ${@constraints.MIN_AB} \leq A, B \leq {@constraints.MAX_AB}$

{@samples.all}

重要なのは、 問題制約とサンプル入出力が問題文ファイルに直接書かれていない ことです。

ここまで作ったファイルの階層を整理してみましょう。以下と同じであれば OK です。

problem.toml
statement.md
tests/
├─ 00_sample_00.in
├─ 00_sample_00.out
├─ 00_sample_01.in
└─ 00_sample_01.out

ツールを実行して出力結果を得る

ここまで用意できたら、statements-manager を実行していきます。まだインストールしていない方は、次のコマンドでインストールしてください。

$ pip install statements-manager

インストール後、 problem.toml と同じ階層で以下のコマンドを実行します。

$ ss-manager run

実行が終わると ss-out/A.html というファイルと、 tests/constraints.hpp というファイルが出来ているはずです。

ss-out/A.html ファイルは、問題制約やサンプルが埋め込まれた後の HTML 形式の問題文です。

tests/constraints.hpp は、問題制約が書かれた C++ 形式のファイルであり、内容は以下のとおりです。 このファイルを使ってデータセットを作ることで、問題文と同じ制約でデータセットを作ることができます。