From 6c21b03f10d40edbbeab8d3e196d186423a8b3ae Mon Sep 17 00:00:00 2001 From: monoid Date: Thu, 21 Apr 2022 20:29:52 +0900 Subject: [PATCH] doc generate by template --- cli.py | 10 ++++-- tools/printDocument.ts | 60 ++++++++++++++++++++++------------ tools/template/intro.md | 4 ++- tools/template/overall.md | 3 -- tools/template/specific.md | 67 +++++--------------------------------- 5 files changed, 58 insertions(+), 86 deletions(-) diff --git a/cli.py b/cli.py index e382550..7dfd08a 100644 --- a/cli.py +++ b/cli.py @@ -11,18 +11,24 @@ def build(args): parser.add_argument('-v', '--verbose', action='store_true', help='verbose mode') parser.add_argument('--update_issues', action='store_true', help='update issues') parser.add_argument('--outDir', default="build", help='output directory') + parser.add_argument('-w', '--watch', action='store_true', help='watch for changes') args = parser.parse_args(args) if args.verbose: print("build start") + + issuePath = os.path.join(args.outDir,"issues.json") if args.update_issues: if args.verbose: print("get issues") - p = subprocess.run(["deno", "run", "-A","tools/getIssue.ts", "--path",os.path.join(args.outDir,"/issues.json")]) + p = subprocess.run(["deno", "run", "-A","tools/getIssue.ts", "--path",issuePath]) p.check_returncode() if args.verbose: print("build issues") - p = subprocess.run(["deno", "run", "-A","tools/printDocument.ts", "--issue_path", "./build/issues.json", "--outDir", args.outDir]) + cmd = ["deno", "run", "-A","tools/printDocument.ts", "--issue_path", issuePath, "--outDir", args.outDir] + if args.watch: + cmd.append("--watch") + p = subprocess.run(cmd) p.check_returncode() def help(_args): diff --git a/tools/printDocument.ts b/tools/printDocument.ts index f36e633..1aab258 100644 --- a/tools/printDocument.ts +++ b/tools/printDocument.ts @@ -2,7 +2,7 @@ import { Issue } from "./githubType.ts"; import { readAll } from "https://deno.land/std@0.135.0/streams/mod.ts" import { parse as argParse } from "https://deno.land/std@0.135.0/flags/mod.ts"; -import { normalize, join as pathJoin, fromFileUrl } from "https://deno.land/std@0.135.0/path/mod.ts"; +import { normalize, join as pathJoin, fromFileUrl, parse as parsePath } from "https://deno.land/std@0.135.0/path/mod.ts"; import * as Eta from "https://deno.land/x/eta@v1.12.3/mod.ts"; async function readContent(path?: string): Promise { @@ -18,22 +18,18 @@ async function readContent(path?: string): Promise { else throw new Error("No input provided. path or stdin."); return content; } - -type DocType = "overall.md" | "specific.md" |"intro.md" | "SUMMARY.md" | "support.md"; -const targets: DocType[] = ["SUMMARY.md", "overall.md", "specific.md", "intro.md", "support.md"]; - type printDocParam = { - target: DocType, - data:{ + target: string, + data: { issues: Issue[] } }; -async function printDoc(param: printDocParam,option? : { +async function printDoc(param: printDocParam, option?: { outDir?: string -}){ +}) { option = option ?? {}; - const {target , data } = param; + const { target, data } = param; const { outDir } = option; let print: string = ""; @@ -50,20 +46,22 @@ async function printDoc(param: printDocParam,option? : { async function readAndPrint(args: { issue_path?: string, - outDir?: string + outDir?: string, + targets: string[], }) { const c = await readContent(args.issue_path); const issues = JSON.parse(c) as Issue[]; issues.sort((a, b) => a.number - b.number); - for(const target of targets){ + for (const target of args.targets) { await printDoc({ target: target, data: { issues - }} - ,{ - outDir: args.outDir - }); + } + } + , { + outDir: args.outDir + }); } } @@ -99,7 +97,10 @@ async function main() { const c = await readContent(issue_path); const issues = JSON.parse(c) as Issue[]; issues.sort((a, b) => a.number - b.number); - await readAndPrint({ issue_path, outDir }); + + const targets = ["SUMMARY.md", "overall.md", "specific.md", "intro.md", "support.md"]; + + await readAndPrint({ issue_path, outDir, targets }); if (watchMode) { const watcher = Deno.watchFs([viewPath, issue_path as string]); for await (const event of watcher) { @@ -108,10 +109,27 @@ async function main() { new TextEncoder().encode("\x1b[2J\x1b[0f"), ); console.log(`reloading ${event.paths.join(", ")}`); - readAndPrint({ - issue_path: issue_path as string, - outDir: outDir as string - }); + let reloadAll = false; + for (const path of event.paths) { + const p = parsePath(path); + if (targets.includes(p.base)) { + readAndPrint({ + issue_path: issue_path as string, + outDir: outDir as string, + targets: [p.base] + }); + } + else{ + reloadAll = true; + } + } + if (reloadAll) { + readAndPrint({ + issue_path: issue_path as string, + outDir: outDir as string, + targets: targets + }); + } } } } diff --git a/tools/template/intro.md b/tools/template/intro.md index ec223f1..c766d49 100644 --- a/tools/template/intro.md +++ b/tools/template/intro.md @@ -1,10 +1,12 @@ # 1. 소개(Introduction) +> Version : 1.0.0 + 본 문서는 전북대학교 컴퓨터공학과의 Floor 팀에서 Scrap Yard라는 어플리케이션을 설계 및 구현하기 위한 소프트웨어 요구사항 명세서(SRS)이다. ## 목적(Purpose) -본 문서의 목적은 프로젝트의 관련된 모든 아이디어들을 정리하고 분석해서 나열하는 것이다. 또한 프로젝트를 더 잘 이해하기 위해 이 제품이 어떻게 사용될지 예측하고 분류하고, 나중에 개발될 요소를 설명하고, 고려 중이지만 폐기될 수 있는 요구사항들을 문서화합니다. +본 문서의 목적은 프로젝트의 관련된 모든 아이디어들을 정리하고 분석해서 나열하는 것이다. 또한 프로젝트를 더 잘 이해하기 위해 이 제품이 어떻게 사용될지 예측하고 분류하고, 나중에 개발될 요소를 설명하고, 고려 중이지만 폐기될 수 있는 요구사항들을 문서화한다. ## 범위(Scope) diff --git a/tools/template/overall.md b/tools/template/overall.md index e88d122..660359b 100644 --- a/tools/template/overall.md +++ b/tools/template/overall.md @@ -77,9 +77,6 @@ - 이 프로젝트는 MIT License로 개발되고 있으므로 라이브러리의 라이센스도 신경을 쓴다. - XSS 공격에 안전해야 한다. -- 1000 RPS에서 문제없이 작동한다. -- 첫 로드후 로딩하면 0.5s 이내에 동작해야합ㄴ.다 -- 동시 편집 이용자를 5명까지는 허용해야 합니다. ## 2.5. 가정 및 의존성(Assumptions and dependencies) diff --git a/tools/template/specific.md b/tools/template/specific.md index 1c20257..b864b76 100644 --- a/tools/template/specific.md +++ b/tools/template/specific.md @@ -1,42 +1,17 @@ # 3. 상세요구사항(Specific Requirements) -> - 설계자가 요구사항을 만족하는 시스템을 설계할 수 있도록 모든 요구사항을 상세하게 포함해야 한다. -> - 테스터가 시스템이 위 요건을 충족하는지 테스트해야 한다. -> - 모든 요구사항은 사용자, 운영자, 다른 외부 시스템에 의해 외부적으로 인지할 수 있어야 한다. -> - 이 요구사항에는 시스템에 대한 모든 입력(자극)과 출력(응답) 그리고 입력 또는 출력 지원에 대한 응답으로 실행되는 모든 기능에 관한 설명이 포함되어야 한다. -> - 상세 요구사항을 작성하기 위한 원칙 -> 1. 상세 요구사항은 "Characteristics of a good SRS"에 설명한 모든 특성을 준수하도록 작성되어야 한다. -> 1. 상세 요구사항은 관련이 있는 이전 문서들과 상호 참조되어야 한다. -> 1. 모든 요구사항은 고유하게 식별할 수 있어야 한다. -> 1. 가독성을 높이기 위해 요구사항을 구성할 때 주의를 기울여야 한다. - ## 3.1. 외부 인터페이스 요구사항(External interface requirements) 해당되지 않음. ## 3.2. 기능 요구사항(Functional requirements) -<%~ it.issues.map(i => `### (${i.number}) ${i.title}\n${i.body}`).join("\n\n") %> - -> - 기능 요구사항은 소프트웨어가 입력을 처리하고 출력을 생성하는 기본적인 행동을 정의해야 한다. -> - 포함하는 행동들 -> 1. Validity checks on the inputs -> 1. Exact sequence of operations -> 1. Responses to abnormal situations, including -> 1. Overflow -> 1. Communication facilities -> 1. Error handling and recovery -> 1. Effect of parameters -> 1. Relationship of outputs to inputs, including -> 1. Input/output sequences -> 1. Formulas for input to output conversion +<%~ it.issues.map(i => `### (#${i.number}) ${i.title}\n${i.body}`).join("\n\n") %> ## 3.3. 성능 요구사항(Performance requirements) -> - 소프트웨어 또는 소프트웨어와 사람의 상호작용에 대하여 수치화된 정적/동적 요구사항이 명시되어야 한다. -> - 수치화된 정적 요구사항의 종류 -> 1. 지원할 터미널 수 -> 1. 지원할 동시 접속 사용자 수 -> 1. 처리할 정보의 양과 유형작업 및 데이터의 양 +1. 최소 1000 RPS를 보장해야한다. +2. 첫 로드후 로딩하면 0.5s 이내에 동작해야합니다 +3. 동시 편집 이용자를 5명까지는 허용해야 합니다. ## 3.4. 논리적 데이터베이스 요구사항(Logical database requirements) @@ -51,48 +26,22 @@ ## 3.5. 설계 제약사항(Design constraints) -> - 다른 표준, 하드웨어 한계 등에 의해 부과될 수 있는 설계 제약사항을 명시해야 한다. +해당되지 않음. ### 3.5.1. 표준 준수(Standards compliance) 해당되지 않음. + ## 3.6. 소프트웨어 시스템 속성(Software system attributes) -> - 요구사항으로 사용될 수 있는 소프트웨어의 여러 가지 속성 중 제품이 객관적으로 입증되는 데 필요한 속성을 명시해야 한다. - -### 3.6.1. 신뢰성(Reliability) - -> - 배포될 때 소프트웨어 시스템의 필수 신뢰성을 확립하는 데 필요한 요소를 명시해야 한다. - -### 3.6.2. 가용성(Availability) - -> - 검사, 복구, 재시작과 같이 전체 시스템에 대해 정의된 가용성 수준을 보장하는 데 필요한 요소가 지정되어야 한다. - -### 3.6.3. 보안성(Security) - -> - 실수 또는 악의적인 접근, 사용, 수정, 파괴, 공개로부터 소프트웨어를 보호하기 위한 요소를 명시해야 한다. -> - 포함될 수 있는 요구사항 -> 1. Utilize certain cryptographical techinques -> 1. Keep specific log or history data sets -> 1. Assign certain functions to diffrent modules -> 1. Restrict communication between some areas of the program -> 1. Check data integrity for critical variables - -### 3.6.4. 유지 보수성(Maintainability) - -> - 소프트웨어 자체를 쉽게 유지 보수할 수 있는 속성을 명시해야 한다. -> - 모듈화, 인터페이스, 복잡성 등과 관련된 요구사항이 있을 수 있다. - -### 3.6.5. 이식성(Portability) - 해당되지 않음. ## 3.7. 상세 요구사항의 구성(Organizing the specific requirements) -> - 시스템의 세부 요구사항은 광범위한 경향이 있으므로 자료를 이해하기에 가장 적합한 방식으로 구성하는 방법을 세심하게 고려해야 한다. - ### 3.7.1. 시스템 모드(System mode) +`production`과 `development` 모드가 있다. + > - 일부 시스템은 운영 모드에 따라 상당히 다르게 작동할 수 있다. > - 예: 제어 시스템은 연습, 일반, 긴급 등의 여러 모드가 있을 수 있다.