Update how to use the update-imported-docs tool (#16777)
Update kubernetes-components.md with software versions. Move content from README to kubernetes-components to avoid duplication. Be listed in the `kubernetes/website/data/reference.yml` file Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>pull/16913/head
aimeeu
Kubernetes Prow Robot
parent
18a466afd0
commit
b1bd43f9d7
|
|
@ -17,66 +17,48 @@ reference documentation for tools and components in the
|
|||
|
||||
* You need to have this software installed:
|
||||
|
||||
* [Python 2.7.16](https://www.python.org/downloads/)
|
||||
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
||||
* [Golang](https://golang.org/doc/install) version 1.9 or later
|
||||
* [Golang](https://golang.org/doc/install) version 1.12 for Kubernetes 1.14+; Go 1.13 [is not supported](https://github.com/kubernetes/community/blob/master/contributors/devel/development.md#go)
|
||||
* [PyYAML](https://pyyaml.org/) v3.13
|
||||
* [make](https://www.gnu.org/software/make/)
|
||||
* [gcc compiler/linker](https://gcc.gnu.org/)
|
||||
|
||||
* Your `$GOPATH` environment variable must be set.
|
||||
* The Go binary must be in your path; **do not** set your `$GOPATH`. The `update-imported-docs` tool sets your GOPATH.
|
||||
|
||||
* You need to know how to create a pull request to a GitHub repository.
|
||||
Typically, this involves creating a fork of the repository. For more
|
||||
information, see [Creating a Documentation Pull Request](/docs/contribute/start/).
|
||||
This involves creating your own fork of the repository. For more
|
||||
information, see [Work from a local clone](/docs/contribute/intermediate/#work_from_a_local_clone).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Getting two repositories
|
||||
## Getting the repository
|
||||
|
||||
If you don't already have the `kubernetes/website` repository, get it now:
|
||||
Make sure your `website` fork is up-to-date with the `kubernetes/website` master and then clone your `website` fork.
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/website
|
||||
mkdir github.com
|
||||
cd github.com
|
||||
git clone git@github.com:<your_github_username>/website.git
|
||||
```
|
||||
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
For example, if you followed the preceding step to get the repository,
|
||||
your base directory is `$GOPATH/src/github.com/kubernetes/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
Determine the base directory of your clone. For example, if you followed the
|
||||
preceding step to get the repository, your base directory is
|
||||
`$github.com/website.` The remaining steps refer to your base directory as
|
||||
`<web-base>`.
|
||||
|
||||
If you plan on making changes to the ref docs, and if you don't already have
|
||||
the `kubernetes/kubernetes` repository, get it now:
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/kubernetes
|
||||
```
|
||||
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository,
|
||||
your base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
|
||||
The reference documentation for the Kubernetes components and tools is automatically
|
||||
generated from the Kubernetes source code. If you want to change the reference documentation,
|
||||
please follow [this guide](/docs/contribute/generate-ref-docs/contribute-upstream).
|
||||
|
||||
{{< note >}}
|
||||
If you only need to generate, but not change, the reference docs, you don't need to
|
||||
manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs`
|
||||
tool, it automatically clones the `kubernetes/kubernetes` repository.
|
||||
{{< /note >}}
|
||||
The reference documentation for the Kubernetes components and tools is generated
|
||||
from the Kubernetes source code. The `update-imported-docs` tool automatically
|
||||
clones the `kubernetes/kubernetes` repository. If you want to change the
|
||||
reference documentation, please follow [this
|
||||
guide](/docs/contribute/generate-ref-docs/contribute-upstream).
|
||||
|
||||
## Overview of update-imported-docs
|
||||
|
||||
The `update-imported-docs` tool is located in the `kubernetes/website/update-imported-docs/`
|
||||
directory. The tool performs the following steps:
|
||||
directory. The tool consists of a Python script that reads a YAML configuration file and performs the following steps:
|
||||
|
||||
1. Clones the related repositories specified in a configuration file. For the
|
||||
purpose of generating reference docs, the repository that is cloned by
|
||||
|
|
@ -91,7 +73,43 @@ When the Markdown files are in your local clone of the `kubernetes/website`
|
|||
repository, you can submit them in a [pull request](/docs/contribute/start/)
|
||||
to `kubernetes/website`.
|
||||
|
||||
## Customizing the config file
|
||||
## Configuration file format
|
||||
|
||||
Each config file may contain multiple repos that will be imported together.
|
||||
When necessary, you can customize the configuration file by manually editing
|
||||
it. You may create new config files for importing other groups of documents. Imported documents must follow these guidelines:
|
||||
|
||||
1. Adhere to the [Documentation Style Guide](/docs/contribute/style/style-guide/).
|
||||
|
||||
1. Have `title` defined in the front matter. For example:
|
||||
|
||||
```
|
||||
---
|
||||
title: Title Displayed in Table of Contents
|
||||
---
|
||||
|
||||
Rest of the .md file...
|
||||
```
|
||||
1. Be listed in the `kubernetes/website/data/reference.yml` file
|
||||
|
||||
The following is an example of the YAML configuration file:
|
||||
|
||||
```yaml
|
||||
repos:
|
||||
- name: community
|
||||
remote: https://github.com/kubernetes/community.git
|
||||
branch: master
|
||||
files:
|
||||
- src: contributors/devel/README.md
|
||||
dst: docs/imported/community/devel.md
|
||||
- src: contributors/guide/README.md
|
||||
dst: docs/imported/community/guide.md
|
||||
```
|
||||
|
||||
Note: `generate-command` is an optional entry, which can be used to run a
|
||||
given command or a short script to generate the docs from within a repo.
|
||||
|
||||
## Customizing the reference.yml config file
|
||||
|
||||
Open `<web-base>/update-imported-docs/reference.yml` for editing.
|
||||
Do not change the content for the `generate-command` entry unless you understand
|
||||
|
|
@ -108,7 +126,7 @@ repos:
|
|||
cd $GOPATH
|
||||
git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
|
||||
cd src/k8s.io/kubernetes
|
||||
git checkout release-1.11
|
||||
git checkout release-1.16
|
||||
make generated_files
|
||||
cp -L -R vendor $GOPATH/src
|
||||
rm -r vendor
|
||||
|
|
@ -154,6 +172,12 @@ cd <web-base>/update-imported-docs
|
|||
./update-imported-docs reference.yml
|
||||
```
|
||||
|
||||
## Fixing Links
|
||||
|
||||
To fix relative links within your imported files, set the repo config's
|
||||
`gen-absolute-links` property to `true`. You can find an example of this in
|
||||
[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml).
|
||||
|
||||
## Adding and committing changes in kubernetes/website
|
||||
|
||||
List the files that were generated and copied to the `kubernetes/website`
|
||||
|
|
|
|||
|
|
@ -1,68 +1,5 @@
|
|||
# Update imported docs
|
||||
|
||||
This script updates the docs files that are generated from other repos.
|
||||
It accepts a YAML file name as its input which can be customized on a per-repo
|
||||
basis.
|
||||
This tool updates the reference docs generated from the Kubernetes repository.
|
||||
|
||||
## Requirements
|
||||
|
||||
Imported docs must follow these guidelines:
|
||||
|
||||
1. Adhere to the [Documentation Style Guide](/docs/home/contribute/style-guide/).
|
||||
|
||||
1. Have `title` defined in the front matter. For example:
|
||||
|
||||
```
|
||||
---
|
||||
title: Title Displayed in Table of Contents
|
||||
---
|
||||
|
||||
Rest of the .md file...
|
||||
```
|
||||
1. Be listed somewhere in a file under the `data` subdirectory, for example,
|
||||
the `data/imported.yml` file.
|
||||
|
||||
1. Make sure the `PyYAML` package is installed:
|
||||
|
||||
```
|
||||
sudo apt-get install python-pip
|
||||
pip install PyYAML
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
From within this directory, run the following command:
|
||||
|
||||
```
|
||||
+./update-imported-docs <CONFIG-FILE>
|
||||
```
|
||||
|
||||
where `<CONFIG-FILE>` can be any YAML configuration file in this directory.
|
||||
|
||||
## Configuration file format
|
||||
|
||||
Each config file may contain multiple repos that will be imported together.
|
||||
When necessary, you can customize the configuration file by manually editing
|
||||
it. You may create new config files for importing other groups of documents.
|
||||
The following is an example of the YAML configuration file:
|
||||
|
||||
```
|
||||
repos:
|
||||
- name: community
|
||||
remote: https://github.com/kubernetes/community.git
|
||||
branch: master
|
||||
files:
|
||||
- src: contributors/devel/README.md
|
||||
dst: docs/imported/community/devel.md
|
||||
- src: contributors/guide/README.md
|
||||
dst: docs/imported/community/guide.md
|
||||
```
|
||||
|
||||
Note: `generate-command` is an optional entry, which can be used to run a
|
||||
given command or a short script to generate the docs from within a repo.
|
||||
|
||||
## Fixing Links
|
||||
|
||||
To fix relative links within your imported files, set the repo config's
|
||||
`gen-absolute-links` property to `true`. You can find an example of this in
|
||||
[`release.yml`](release.yml).
|
||||
[Generating Reference Pages for Kubernetes Components and Tools](https://kubernetes.io/docs/contribute/generate-ref-docs/kubernetes-components/) contains detailed instructions for using this tool.
|
||||
|
|
|
|||
Loading…
Reference in New Issue