Skip to content

Commit

Permalink
Update how to use the update-imported-docs tool
Browse files Browse the repository at this point in the history 
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 <[email protected]>
  • Loading branch information
@aimeeu
aimeeu committed Oct 9, 2019
1 parent d99bfec commit 2094557
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 106 deletions.
106 changes: 65 additions & 41 deletions content/en/docs/contribute/generate-ref-docs/kubernetes-components.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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`
Expand Down
67 changes: 2 additions & 65 deletions update-imported-docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 2094557

Please sign in to comment.