Merge upstream work for release-1.19
This commit is contained in:
inductor
@@ -54,8 +54,8 @@ card:
|
||||
#### 既存のページの誤字脱字や古い記述を修正する場合の手順
|
||||
|
||||
1. `kubernetes/website`リポジトリをフォークする
|
||||
2. `dev-1.18-ja.1`(最新のマイルストーンブランチに適宜読み替えること)から任意の名前でブランチを作成し、該当箇所を編集する
|
||||
3. `dev-1.18-ja.1`(最新のマイルストーンブランチに適宜読み替えること)ブランチに向けてPull Requestを作成する
|
||||
2. `dev-1.18-ja.2`(最新のマイルストーンブランチに適宜読み替えること)から任意の名前でブランチを作成し、該当箇所を編集する
|
||||
3. `dev-1.18-ja.2`(最新のマイルストーンブランチに適宜読み替えること)ブランチに向けてPull Requestを作成する
|
||||
|
||||
### マイルストーンについて {#milestones}
|
||||
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 変更のレビュー
|
||||
weight: 30
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
このセクションでは、コンテンツのレビュー方法について説明します。
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: ドキュメントコンテンツガイド
|
||||
linktitle: コンテンツガイド
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
このページでは、Kubernetesのドキュメント上のコンテンツのガイドラインを説明します。
|
||||
|
||||
許可されるコンテンツに関して疑問がある場合は、[Kubernetes Slack](https://slack.k8s.io/)の#sig-docsチャンネルに参加して質問してください！
|
||||
|
||||
Kubernetes Slackには、<https://slack.k8s.io/> から参加登録ができます。
|
||||
|
||||
Kubernetesドキュメントの新しいコンテンツの作成に関する情報については、[スタイルガイド](/docs/contribute/style/style-guide)に従ってください。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## 概要
|
||||
|
||||
ドキュメントを含むKubernetesのウェブサイトのソースは、[kubernetes/website](https://github.com/kubernetes/website)リポジトリに置かれています。
|
||||
|
||||
Kubernetesの主要なドキュメントは`kubernetes/website/content/<language_code>/docs`フォルダに置かれており、これらは[Kubernetesプロジェクト](https://github.com/kubernetes/kubernetes)を対象としています。
|
||||
|
||||
## 許可されるコンテンツ
|
||||
|
||||
Kubernetesのドキュメントにサードパーティーのコンテンツを掲載することが許されるのは、次の場合のみです。
|
||||
|
||||
- コンテンツがKubernetesプロジェクト内のソフトウェアのドキュメントとなる場合
|
||||
- コンテンツがプロジェクト外のソフトウェアのドキュメントとなるが、Kubernetesを機能させるために必要である場合
|
||||
- コンテンツがkubernetes.ioの正規のコンテンツであるか、他の場所の正規のコンテンツへのリンクである場合
|
||||
|
||||
### サードパーティーのコンテンツ
|
||||
|
||||
Kubernetesのドキュメントには、Kubernetesプロジェクト([kubernetes](https://github.com/kubernetes)および[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizationsに存在するプロジェクト)の適用例が含まれています。
|
||||
|
||||
Kubernetesプロジェクト内のアクティブなコンテンツへのリンクは常に許可されます。
|
||||
|
||||
Kubernetesを機能させるためには、一部サードパーティーのコンテンツが必要です。たとえば、コンテナランタイム(containerd、CRI-O、Docker)、[ネットワークポリシー](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/)(CNI plugin)、[Ingressコントローラー](/ja/docs/concepts/services-networking/ingress-controllers/)、[ロギング](/docs/concepts/cluster-administration/logging/)などです。
|
||||
|
||||
ドキュメント内で、Kubernetesプロジェクト外のサードパーティーのオープンソースソフトウェア(OSS)にリンクすることができるのは、Kubernetesを機能させるために必要な場合のみです。
|
||||
|
||||
### 情報源が重複するコンテンツ
|
||||
|
||||
可能な限り、Kubernetesのドキュメントは正規の情報源にリンクするようにし、情報源が重複してしまうようなホスティングは行いません。
|
||||
|
||||
情報源が重複したコンテンツは、メンテナンスするために2倍の労力(あるいはそれ以上！)が必要になり、より早く情報が古くなってしまいます。
|
||||
|
||||
{{< note >}}
|
||||
|
||||
あなたがKubernetesのプロジェクトのメンテナーであり、ドキュメントのホスティングに関して手助けが必要なときは、[Kubernetes Slackの#sig-docs](https://kubernetes.slack.com/messages/C1J0BPD2M/)で教えてください。
|
||||
|
||||
{{< /note >}}
|
||||
|
||||
### その他の情報
|
||||
|
||||
許可されるコンテンツに関して疑問がある場合は、[Kubernetes Slack](https://slack.k8s.io/)の#sig-docsチャンネルに参加して質問してください！
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [スタイルガイド](/docs/contribute/style/style-guide)を読む
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: コンテンツの構造化
|
||||
content_type: concept
|
||||
weight: 40
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
このサイトではHugoを使用しています。Hugoでは、[コンテンツの構造化](https://gohugo.io/content-management/organization/)がコアコンセプトとなっています。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
{{% note %}}
|
||||
**Hugoのヒント:** コンテンツの編集を始めるときは、`hugo server --navigateToChanged`コマンドを使用してHugoを実行してください。
|
||||
{{% /note %}}
|
||||
|
||||
## ページの一覧
|
||||
|
||||
### ページの順序
|
||||
|
||||
ドキュメントのサイドメニューやページブラウザーなどでは、Hugoのデフォルトのソート順序を使用して一覧を作成しています。デフォルトでは、weight(1から開始)、日付(最新のものが1番目)、最後にリンクのタイトルの順でソートされます。
|
||||
|
||||
そのため、特定のページやセッションを上に移動したい場合には、ページのフロントマター内のweightを設定します。
|
||||
|
||||
```yaml
|
||||
title: My Page
|
||||
weight: 10
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
ページのweightについては、1、2、3…などの値を使用せず、10、20、30…のように一定の間隔を空けた方が賢明です。こうすることで、後で別のページを間に挿入できるようになります。
|
||||
{{% /note %}}
|
||||
|
||||
### ドキュメントのメインメニュー
|
||||
|
||||
ドキュメントのメインメニューは、`docs/`以下に置かれたセクションのコンテンツファイル`_index.md`のフロントマター内に`main_menu`フラグが設定されたものから生成されます。
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
```
|
||||
|
||||
リンクのタイトルは、ページの`linkTitle`から取得されることに注意してください。そのため、ページのタイトルとは異なるリンクテキストにしたい場合、コンテンツファイル内の値を以下のように設定します。
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
title: ページタイトル
|
||||
linkTitle: リンク内で使われるタイトル
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
上記の設定は言語ごとに行う必要があります。メニュー上にセクションが表示されないときは、Hugoからセクションとして認識されていないためである可能性が高いです。セクションフォルダー内に`_index.md`コンテンツファイルを作成してください。
|
||||
{{% /note %}}
|
||||
|
||||
### ドキュメントのサイドメニュー
|
||||
|
||||
ドキュメントのサイドバーメニューは、`docs/`以下の*現在のセクションツリー*から生成されます。
|
||||
|
||||
セクションと、そのセクション内のページがすべて表示されます。
|
||||
|
||||
特定のセクションやページをリストに表示したくない場合、フロントマター内の`toc_hide`フラグを`true`に設定してください。
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
コンテンツが存在するセクションに移動すると、特定のセクションまたはページ(例:`index.md`)が表示されます。それ以外の場合、そのセクションの最初のページが表示されます。
|
||||
|
||||
### ドキュメントのブラウザー
|
||||
|
||||
ドキュメントのホームページのページブラウザーは、`docs`セクション直下のすべてのセクションとページを使用して生成されています。
|
||||
|
||||
特定のセクションやページを表示したくない場合、フロントマターの`toc_hide`フラグを`true`に設定してください。
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
### メインメニュー
|
||||
|
||||
右上のメニュー(およびフッター)にあるサイトリンクは、page-lookupの機能を使用して実装されています。これにより、ページが実際に存在することを保証しています。そのため、たとえば`case-studies`のセクションが特定の言語のサイトに存在しない場合、メニューにはケーススタディのリンクが表示されません。
|
||||
|
||||
## Page Bundle
|
||||
|
||||
スタンドアローンのコンテンツページ(Markdownファイル)に加えて、Hugoでは、[Page Bundles](https://gohugo.io/content-management/page-bundles/)がサポートされています。
|
||||
|
||||
Page Bundleの1つの例は、[カスタムのHugo Shortcode](/docs/contribute/style/hugo-shortcodes/)です。これは、`leaf bundle`であると見做されます。ディレクトリ内のすべてのファイルは、`index.md`を含めてバンドルの一部となります。これには、ページからの相対リンク、処理可能な画像なども含まれます。
|
||||
|
||||
```bash
|
||||
en/docs/home/contribute/includes
|
||||
├── example1.md
|
||||
├── example2.md
|
||||
├── index.md
|
||||
└── podtemplate.json
|
||||
```
|
||||
|
||||
もう1つのPage Bundleがよく使われる例は、`includes`バンドルです。フロントマターに`headless: true`を設定すると、自分自身のURLを持たなくなり、他のページ内でのみ使用されるようになります。
|
||||
|
||||
```bash
|
||||
en/includes
|
||||
├── default-storage-class-prereqs.md
|
||||
├── index.md
|
||||
├── partner-script.js
|
||||
├── partner-style.css
|
||||
├── task-tutorial-prereqs.md
|
||||
├── user-guide-content-moved.md
|
||||
└── user-guide-migration-notice.md
|
||||
```
|
||||
|
||||
バンドル内のファイルに関して、いくつか重要な注意点があります。
|
||||
|
||||
* 翻訳されたバンドルに対しては、コンテンツ以外の見つからなかったファイルは上位の言語から継承されます。これにより重複が回避できます。
|
||||
* バンドル内のすべてのファイルは、Hugoが`Resources`と呼ぶファイルになり、フロントマター(YAMLファイルなど)をサポートしていない場合であっても、言語ごとにパラメーターやタイトルなどのメタデータを提供できます。詳しくは、[Page Resourcesメタデータ](https://gohugo.io/content-management/page-resources/#page-resources-metadata)を参照してください。
|
||||
* `Resource`の`.RelPermalink`から取得した値は、ページからの相対的なものとなっています。詳しくは、[Permalinks](https://gohugo.io/content-management/urls/#permalinks)を参照してください。
|
||||
|
||||
## スタイル
|
||||
|
||||
このサイトのスタイルシートの[SASS](https://sass-lang.com/)のソースは、`assets/sass`に置かれていて、Hugoによって自動的にビルドされます。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [カスタムのHugo shortcode](/docs/contribute/style/hugo-shortcodes/)について学ぶ
|
||||
* [スタイルガイド](/docs/contribute/style/style-guide)について学ぶ
|
||||
* [コンテンツガイド](/docs/contribute/style/content-guide)について学ぶ
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: コンテンツの改善を提案する
|
||||
slug: suggest-improvements
|
||||
content_type: concept
|
||||
weight: 10
|
||||
card:
|
||||
name: contribute
|
||||
weight: 20
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
Kubernetesのドキュメントに何か問題を見つけたり、新しいコンテンツに関してアイデアを思い付いたときは、issueを作ってください。必要なものは、[GitHubアカウント](https://github.com/join)とウェブブラウザーだけです。
|
||||
|
||||
Kubernetesのドキュメント上の新しい作業は、ほとんどの場合、GitHubのissueから始まります。Kubernetesのコントリビューターは、必要に応じてレビュー、分類、タグ付けを行います。次に、あなたやKubernetesコミュニティの他のメンバーが、そのissueを解決するための変更を加えるpull requestを開きます。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## issueを作る
|
||||
|
||||
既存のコンテンツに対して改善を提案したい場合や、間違いを発見した場合は、issueを作ってください。
|
||||
|
||||
1. ページの右側のサイドバーにある**ドキュメントのissueを作成**ボタンをクリックします。GitHubのissueページにリダイレクトし、一部のヘッダーが自動的に挿入されます。
|
||||
2. 問題や改善の提案について書きます。できる限り多くの詳細情報を提供するようにしてください。
|
||||
3. **Submit new issue**ボタンをクリックします。
|
||||
|
||||
送信後、定期的にissueを確認するか、GitHubの通知を設定してください。レビュアや他のコミュニティメンバーが、issueに対して作業を行うために、あなたに何か質問をするかもしれません。
|
||||
|
||||
## 新しいコンテンツの提案
|
||||
|
||||
新しいコンテンツに関するアイデアがあるものの、どの場所に追加すればわからないときでも、issueを作ることができます。次のいずれかを選択して行ってください。
|
||||
|
||||
- コンテンツが追加されるべきだと思う既存のページを選択し、**ドキュメントのissueを作成**ボタンをクリックする。
|
||||
- [GitHub](https://github.com/kubernetes/website/issues/new/)に移動し、直接issueを作る。
|
||||
|
||||
## よいissueを作るには
|
||||
|
||||
issueを作るときは、以下のことを心に留めてください。
|
||||
|
||||
- 明確なissueの説明を書く。不足している点、古くなっている点、誤っている点、改善が必要な点など、どの点がそうであるか明確に書く。
|
||||
- issueがユーザーに与える具体的な影響を説明する。
|
||||
- 合理的な作業単位になるように、特定のissueのスコープを制限する。スコープの大きな問題については、小さな複数のissueに分割する。たとえば、"Fix the security docs"(セキュリティのドキュメントを修正する)というのはスコープが大きすぎますが、"Add details to the 'Restricting network access' topic"(トピック「ネットワークアクセスの制限」に詳細情報を追加する)であれば十分に作業可能な大きさです。
|
||||
- すでにあるissueを検索し、関連または同様のissueがないかどうか確認する。
|
||||
- 新しいissueがほかのissueやpull requestと関係する場合は、完全なURLを参照するか、issueやpull requestの数字の前に`#`の文字を付けて参照する。例えば、`Introduced by #987654`のように書きます。
|
||||
- [行動規範](/ja/community/code-of-conduct/)に従って、仲間のコントリビューターに敬意を払いましょう。たとえば、"The docs are terrible"(このドキュメントは最悪だ)のようなコメントは、役に立つ敬意のあるフィードバックではありません。
|
||||
Reference in New Issue
Block a user