From b1bd43f9d7366848f182b41eaca294139f873a3e Mon Sep 17 00:00:00 2001 From: aimeeu Date: Mon, 14 Oct 2019 18:19:52 -0500 Subject: [PATCH] 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 --- .../kubernetes-components.md | 106 +++++++++++------- update-imported-docs/README.md | 67 +---------- 2 files changed, 67 insertions(+), 106 deletions(-) diff --git a/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md b/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md index a1d2ceab06..3336dcd1e2 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md @@ -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:/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 ``. +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 +``. -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 ``. - -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 `/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 /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` diff --git a/update-imported-docs/README.md b/update-imported-docs/README.md index ea1820cf4b..d2a5cf25d9 100644 --- a/update-imported-docs/README.md +++ b/update-imported-docs/README.md @@ -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 -``` - -where `` 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.