Introduction 情報技術ドキュメント例 techdoc-ja は日本語で情報技術ドキュメント ( 仕様書やドキュメント等 ) を記述するためのオーサリング環境を提供します本ドキュメントはその利用実例です要件ドキュメントを Markdown 形式で記述するコードブロックのシンタ

Size: px

Start display at page:

Download "Introduction 情報技術ドキュメント例 techdoc-ja は日本語で情報技術ドキュメント ( 仕様書やドキュメント等 ) を記述するためのオーサリング環境を提供します本ドキュメントはその利用実例です要件ドキュメントを Markdown 形式で記述するコードブロックのシンタ"

ゆゆこひろなが
5 years ago
Views:

1 目次 Introduction ソフトウェアバージョン標準プロジェクト構成具体的な設定例そのほかの使用例

2 Introduction 情報技術ドキュメント例 techdoc-ja は日本語で情報技術ドキュメント ( 仕様書やドキュメント等 ) を記述するためのオーサリング環境を提供します本ドキュメントはその利用実例です要件ドキュメントを Markdown 形式で記述するコードブロックのシンタックスハイライトに対応する PlantUML による作図に対応する日本語の記述に対応する PlantUML 画像内でも日本語が表記できる GitHub でドキュメントプロジェクトを管理し PR で編集する Circle CI によって継続的に次の処理を実行する RedPen および textlint により文章の自動校正をする Gitbook によって HTML および PDF 出力を得る出力結果は Amazon S3 にデプロイする 2

3 ソフトウェアバージョン Section 1 - ソフトウェアバージョン Docker イメージ classmethod/techdoc-ja では次のソフトウェアを利用可能です Node.js v9.3.0 OpenJDK 1.8.0_131 RedPen textlint v GitBook graphviz version ( ) Python/3.4.2 aws-cli

4 標準プロジェクト構成 Section 2 - 標準プロジェクト構成ドキュメントプロジェクトは次のディレクトリ構成を標準とします. +-- README.md -- ドキュメントの運用ビルド方法等 +--.circleci +-- config.yml -- Circle CI 設定 +--.gitignore -- git 設定 +-- book.json -- Gitbook 設定 +-- config -- 校正ツール設定 +-- redpen-conf.xml -- RedPen 設定 +-- redpen-dict +-- stopwords.txt +-- suggest.txt +-- katakana.txt +-- textlint.json -- textlint 設定 content +-- README.md -- ドキュメント本体の README +-- SUMMARY.md -- 目次等その他コンテンツ +-- styles +-- website.css +-- pdf.css +-- _book -- ビルド成果物 +-- index.html +-- techdoc-example.pdf Circle CI と同等の環境下に入る方法 $ docker run --rm -it -v $(pwd):/root/workspace -w /root/workspace classmethod/techdoc-ja:l atest sh 4

5 具体的な設定例 Section 3 - 具体的な設定例 Gitbook 設定例 (book.json) { "root": "./content", "language": "ja", "title": " 情報技術ドキュメント例 ", "styles": { "website": "styles/website.css", "pdf": "styles/pdf.css" "pdf": { "fontsize": 11, "fontfamily": "MigMix 1P" "plugins": [ "include", "include-codeblock", "uml", "-sharing", "alerts", "back-to-top-button", "ace" ], "pluginsconfig": { "include-codeblock": { "template": "acefull" Circle CI 設定例 (.circleci/config.yml) version: 2 jobs: build: working_directory: ~/workspace docker: - image: classmethod/techdoc-ja:latest steps: - checkout - restore_cache: keys: - techdoc-{{.branch -{{.Revision - techdoc-{{.branch - run: name: System information command: 5

6 具体的な設定例 echo "Node $(node -v)" java -version echo "RedPen $(redpen -v)" echo "textlint $(textlint -v)" gitbook current dot -V aws --version - run: name: Check by RedPen command: find./content -name "*.md" -type f xargs redpen ${REDPEN_OPTS -l 0 - L ja -f markdown -c./config/redpen-conf.xml - run: name: Check by textlint command: textlint ${TEXTLINT_OPTS --config./config/textlint.json./content - run: name: Build command: gitbook install gitbook build. if [ -n "${PDF_FILENAME" ]; then gitbook pdf. _book/${pdf_filename fi - store_artifacts: name: Store artifacts path: _book destination: _book - deploy: name: Deploy artifacts command: if [ -n "${AWS_S3_LOCATION_MASTER" -a "${CIRCLE_BRANCH" == "master" ]; then DEPLOY_LOCATION=${AWS_S3_LOCATION_MASTER elif [ -n "${AWS_S3_LOCATION_SNAPSHOT" ]; then DEPLOY_LOCATION=${AWS_S3_LOCATION_SNAPSHOT%//${CIRCLE_BRANCH fi if [ -n "${DEPLOY_LOCATION" ]; then aws s3 sync _book ${DEPLOY_LOCATION --delete fi - save_cache: key: techdoc-{{.branch -{{.Revision paths: - ~/workspace/node_modules Circle CI に設定できる環境変数環境変数名説明例 REDPEN_OPTS RedPen のコマンドライン引数 TEXTLINT_OPTS textlint のコマンドライン引数 --debug PDF_FILENAME AWS_S3_LOCATION_MASTER PDF を出力する場合はその出力ファイル名 master ブランチをデプロイする場合はその S3 URI foobar.pdf s3://exbucket/release/ 6

7 具体的な設定例 AWS_S3_LOCATION_SNAPSHOT その他ブランチをデプロイする場合はその S3 URI s3://exbucket/snapshot/ RedPen 設定例 <redpen-conf lang="ja"> <validators> <validator name="sentencelength" /> <validator name="invalidexpression"> <property name="dict" value="redpen-dict/stopwords.txt"/> </validator> <validator name="commanumber" /> <validator name="suggestexpression"> <property name="dict" value="redpen-dict/suggest.txt"/> </validator> <validator name="invalidsymbol"/> <validator name="katakanaendhyphen"> <property name="dict" value="redpen-dict/katakana.txt"/> </validator> <validator name="katakanaspellcheck"/> <validator name="sectionlength"/> <validator name="paragraphnumber"/> <validator name="spacebetweenalphabeticalword"/> <validator name="successiveword"/> <validator name="doublenegative" /> <validator name="frequentsentencestart" /> <validator name="parenthesizedsentence"> <property name="max_nesting_level" value="1"/> <property name="max_count" value="3"/> <property name="max_length" value="10"/> </validator> <validator name="hankakukana"/> <validator name="okurigana"/> <validator name="gappedsection"/> <validator name="longkanjichain"> <property name="max_len" value="6"/> </validator> <validator name="sectionlevel"/> <validator name="japaneseambiguousnounconjunction" /> <validator name="japanesejoyokanji" /> <validator name="japanesenumberexpression" /> <validator name="japaneseanchorexpression" /> <validator name="successivesentence" /> <validator name="doubledconjunctiveparticlega" /> <validator name="listlevel" /> </validators> <symbols> <symbol name="full_stop" value=" " invalid-chars="." /> <symbol name="comma" value=" " invalid-chars=","/> <symbol name="colon" value=":" /> <symbol name="ampersand" value="&" /> <symbol name="question_mark" value="?" /> <symbol name="dollar_sign" value="$" /> <symbol name="less_than_sign" value="<" /> 7

8 具体的な設定例 <symbol name="greater_than_sign" value=">" /> <symbol name="vertical_bar" value=" " /> <symbol name="percent_sign" value="%" /> <symbol name="exclamation_mark" value="!" /> <symbol name="left_curly_bracket" value="{" /> <symbol name="right_curly_bracket" value="" /> <symbol name="equal_sign" value="=" /> <symbol name="left_square_bracket" value="[" /> <symbol name="right_square_bracket" value="]" /> <symbol name="left_parenthesis" value="(" /> <symbol name="right_parenthesis" value=")" /> <symbol name="at_mark" /> </symbols> </redpen-conf> textlint 設定例 { "rules": { "spellcheck-tech-word": true, "preset-ja-technical-writing": { "no-exclamation-question-mark": false "preset-jtf-style": { " 全角文字と半角文字の間 ": false, "3.3. かっこ類と隣接する文字の間のスペースの有無 ": false "preset-ja-spacing": { "ja-space-between-half-and-full-width": { "space": "always" "ja-no-space-around-parentheses": false "preset-japanese": { "sentence-length": false "no-todo": true, "no-start-duplicated-conjunction": { "interval" : 2 "no-exclamation-question-mark": true, "no-dead-link": { "checkrelative": false, "baseuri": null, "ignore": [] "no-empty-section": true, "date-weekday-mismatch": true, "period-in-list-item": { "periodmarks": [".", "."] "no-nfd": true, "no-surrogate-pair": true, "common-misspellings": { 8

9 具体的な設定例 "ignore": [] "ja-no-redundant-expression": true, "no-mixed-zenkaku-and-hankaku-alphabet": true, "textlint-rule-max-appearence-count-of-words": { "limit": 5 "textlint-rule-max-length-of-title": { "#": 25, "##": 30 "incremental-headers": true, "ja-unnatural-alphabet": true, "@textlint-ja/textlint-rule-no-insert-dropping-sa": true "filters": { "comments": true, "whitelist": { "allow": [ "ignored-word", "/\\d+/" ].gitignore 設定例下記コマンドで作成しましょう $ curl -s >.gitignore $ echo "/assets" >>.gitignore 9

10 そのほかの使用例 Section 4 - そのほかの使用例コードブロックのシンタックスハイライト [ ] { "title": "apples", "count": [12000, 20000], "description": {"text": "...", "sensitive": false { "title": "oranges", "count": [17500, null], "description": {"text": "...", "sensitive": false PlantUML による作図 10

TeX LiveのCIテスティング

TeX LiveのCIテスティング T E X Live の CI テスティング Norbert Preining 北海道大学札幌 2018 年 11 月 10 日概要 Subversion と git の踊り T E X Live sources の CI T E X Live インストーラーの CI まとめ Subversion と git の踊り SvnRepo git svn dcommit git svn fetch DevRepo