From a37d3bcd132475c559fcc8fcf971c09771243002 Mon Sep 17 00:00:00 2001 From: tsuna-can-se <61451753+tsuna-can-se@users.noreply.github.com> Date: Fri, 15 Nov 2024 10:24:40 +0900 Subject: [PATCH] =?UTF-8?q?=E3=83=89=E3=82=AD=E3=83=A5=E3=83=A1=E3=83=B3?= =?UTF-8?q?=E3=83=88=E4=BD=9C=E6=88=90=E6=89=8B=E9=A0=86=E3=81=AE=E7=9B=AE?= =?UTF-8?q?=E6=AC=A1=E6=A7=8B=E9=80=A0=E3=82=92=E4=BF=AE=E6=AD=A3=E3=81=99?= =?UTF-8?q?=E3=82=8B=20(#1556)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * cspellの重複した記述を削除 * 常時参照する部分が前半に来るよう構成を変更 * ドキュメント作成に不要な拡張機能を削除 * cspell ignoreから未使用の用語を削除 --- documents/README.md | 170 +++++++++++++++++++++----------------------- 1 file changed, 81 insertions(+), 89 deletions(-) diff --git a/documents/README.md b/documents/README.md index fcfc45a08..4b14761f1 100644 --- a/documents/README.md +++ b/documents/README.md @@ -1,6 +1,6 @@ - + # AlesInfiny Maia OSS Edition ドキュメントについて ## 本番環境 @@ -58,85 +58,8 @@ documents フォルダー配下のフォルダー、ファイルの配置は以 ## ドキュメント作成手順 -### ドキュメント作成環境の構築 - -#### Visual Studio Code のインストール - -ドキュメント作成のエディターとして、 Visual Studio Code を利用します。 -以下のサイトから最新版の Visual Studio Code をインストールします。 - - - -#### Visual Studio Code の拡張機能のインストール - -Visual Studio Code の [ファイル] メニューから [ワークスペースを開く] を選択します。 -クローンしたフォルダー内にある maia.code-workspace ファイルを選択して開きます。 - -はじめてワークスペースを開いたとき、以下のようなダイアログが表示されるので、 [インストール] ボタンを押下します。 - -![このリポジトリにお勧めの拡張機能をインストールしますか](readme-images/install-vscode-extensions.png) - -このダイアログ経由でインストールしなかった場合は、 [拡張機能] メニューから [推奨] のグループを開いて、以下の拡張機能をインストールします。 - -- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) -- [Draw.io integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) -- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) -- [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) -- [vscode-textlint](https://marketplace.visualstudio.com/items?itemName=taichi.vscode-textlint) - -![拡張機能メニュー](readme-images/recommend-vscode-extensions.png) - -AlesInfiny Maia OSS Edition のリポジトリは Github-flow で開発します。 -Visual Studio Code 上で Pull Request を発行する際には、以下の拡張機能をインストールします。 - -- [Github Pull Requests](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github) - -また、必要に応じて以下の拡張機能をインストールします。 - -- [Japanese Language Pack for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=MS-CEINTL.vscode-language-pack-ja) -- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) -- [Table Formatter](https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter) - -#### Node.js のインストール - -以下のサイトから安定版の Node.js インストーラーをダウンロードし、インストールしてください。 - - - -#### Node モジュールのインストール - -本リポジトリでは textlint を使用して、校正を自動化します。 -以下のコマンドを実行して、 textlint の実行に必要な Node モジュールをインストールしてください。 -モジュールの更新も同じコマンドで実行できます。 - -```plane -npm ci -``` - -#### Pythonのインストール - -以下のサイトから、 Windows 用の最新版 Python をインストールします。 -インストール時に [Add Python 3.x to PATH] へチェックを入れてからインストールしてください。 - - - -コマンドプロンプトを管理者権限で起動します。 -以下のコマンドを実行して pip を更新します。 - -```plain -pip install --upgrade pip -``` - -#### Python モジュールのインストール - -本リポジトリでは、 yamllint を使用して、 YAML ファイルの Lint を自動化します。 -また、 Mkdocs を用いて、マークダウンから Web サイトを生成します。 -以下のコマンドを実行して、必要なモジュールを一括でインストールします。 -モジュールの更新も同じコマンドで実行できます。 - -```plain -pip install -r requirements.txt -``` +最初に「[ドキュメント作成環境の構築](#ドキュメント作成環境の構築)」に従って、ドキュメント作成環境を構築してください。 +ドキュメントの作成にあたり、以下の手順、規則に従って作成してください。 ### ドキュメントの作成 @@ -239,14 +162,7 @@ CSpell の拡張機能をインストールしていると、 [問題] ウィン この拡張機能は、英単語のスペルミスを検出するために導入するものであり、コメントの多くはスペルミスに起因しています。 必ず対応するようにしてください。 -複合語や技術用語は、辞書登録しないと誤検知されることがあります。 -[cspell.json] ファイルの `words` に単語を登録するようにしてください。 - -コード内や設定ファイル内の文字など、単語登録することが望ましくないと考える場合は、以下の記事を参照して、各ページで抑制してください。 -CSpell が実行されないようにするのではなく、そのページ内で使用する抑制しても良い単語を、ページの先頭に記述する方式で抑制しましょう。 -このページの上部にも設定してあります。 - - +詳細は「[用語集の整理](#用語集の整理)」を参照してください。 #### textlint @@ -285,7 +201,8 @@ CSpell の拡張機能をインストールしていると、 [問題] ウィン 以下を参照して、ページ内に `cspell:ignore` を追加して、警告を除外する用語を追加してください。 設定はページ最上部に記述します。 - + - + - ### 各ページの title/description の設定 @@ -397,4 +314,79 @@ Pull Request を発行すると、ドキュメントの体裁をチェックす ![ワークフローでエラーが発生した場合の詳細画面](readme-images/github-lint-error-results.png) +## ドキュメント作成環境の構築 + +### Visual Studio Code のインストール + +ドキュメント作成のエディターとして、 Visual Studio Code を利用します。 +以下のサイトから最新版の Visual Studio Code をインストールします。 + + + +### Visual Studio Code の拡張機能のインストール + +Visual Studio Code の [ファイル] メニューから [ワークスペースを開く] を選択します。 +クローンしたフォルダー内にある maia.code-workspace ファイルを選択して開きます。 + +はじめてワークスペースを開いたとき、以下のようなダイアログが表示されるので、 [インストール] ボタンを押下します。 + +![このリポジトリにお勧めの拡張機能をインストールしますか](readme-images/install-vscode-extensions.png) + +このダイアログ経由でインストールしなかった場合は、 [拡張機能] メニューから [推奨] のグループを開いて、以下の拡張機能をインストールします。 + +- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) +- [Draw.io integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) +- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) +- [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) +- [vscode-textlint](https://marketplace.visualstudio.com/items?itemName=taichi.vscode-textlint) + +![拡張機能メニュー](readme-images/recommend-vscode-extensions.png) + +また、必要に応じて以下の拡張機能をインストールします。 + +- [Japanese Language Pack for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=MS-CEINTL.vscode-language-pack-ja) +- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) +- [Table Formatter](https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter) + +### Node.js のインストール + +以下のサイトから安定版の Node.js インストーラーをダウンロードし、インストールしてください。 + + + +### Node モジュールのインストール + +本リポジトリでは textlint を使用して、校正を自動化します。 +以下のコマンドを実行して、 textlint の実行に必要な Node モジュールをインストールしてください。 +モジュールの更新も同じコマンドで実行できます。 + +```plane +npm ci +``` + +### Pythonのインストール + +以下のサイトから、 Windows 用の最新版 Python をインストールします。 +インストール時に [Add Python 3.x to PATH] へチェックを入れてからインストールしてください。 + + + +コマンドプロンプトを管理者権限で起動します。 +以下のコマンドを実行して pip を更新します。 + +```plain +pip install --upgrade pip +``` + +### Python モジュールのインストール + +本リポジトリでは、 yamllint を使用して、 YAML ファイルの Lint を自動化します。 +また、 Mkdocs を用いて、マークダウンから Web サイトを生成します。 +以下のコマンドを実行して、必要なモジュールを一括でインストールします。 +モジュールの更新も同じコマンドで実行できます。 + +```plain +pip install -r requirements.txt +``` +