From 1ca6c144e791294e4b3fb272c1b95c1faa455436 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Mon, 23 Sep 2019 17:40:30 -0400 Subject: [PATCH] add processing of kubectl cmd links - add processing of kubectl links in update-imported-docs. - update component reference generation guide. - For more information, see issue #16454. --- .../kubernetes-components.md | 21 +++++---- update-imported-docs/reference.yml | 44 +++++++++---------- update-imported-docs/update-imported-docs | 28 +++++++++++- 3 files changed, 58 insertions(+), 35 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 2134ed94d2bbc..d66b510e5914a 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md @@ -7,8 +7,7 @@ content_template: templates/task This page shows how to use the `update-imported-docs` tool to generate reference documentation for tools and components in the -[Kubernetes](https://github.com/kubernetes/kubernetes) and -[Federation](https://github.com/kubernetes/federation) repositories. +[Kubernetes](https://github.com/kubernetes/kubernetes) repository. {{% /capture %}} @@ -66,7 +65,7 @@ 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/gen-ref-docs/contribute-upstream). +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 @@ -80,12 +79,13 @@ The `update-imported-docs` tool is located in the `kubernetes/website/update-imp directory. The tool performs the following steps: 1. Clones the related repositories specified in a configuration file. For the - purpose of generating reference docs, the repositories that are cloned by - default are `kubernetes-incubator/reference-docs` and `kubernetes/federation`. + purpose of generating reference docs, the repository that is cloned by + default is `kubernetes-incubator/reference-docs`. 1. Runs commands under the cloned repositories to prepare the docs generator and then generates the Markdown files. 1. Copies the generated Markdown files to a local clone of the `kubernetes/website` repository under locations specified in the configuration file. +1. Updates `kubectl` command links from `kubectl`.md to the `kubectl` command reference. 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/) @@ -171,12 +171,12 @@ might look like this: ... modified: content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md - modified: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md - modified: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md modified: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md modified: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md modified: content/en/docs/reference/command-line-tools-reference/kube-proxy.md modified: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md + modified: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md + modified: content/en/docs/reference/kubectl/kubectl.md ... ``` @@ -196,8 +196,7 @@ topics will be visible in the {{% capture whatsnext %}} -* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/) -* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/) -* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/) -* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/gen-ref-docs/contribute-upstream) +* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/) +* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) +* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/generate-ref-docs/contribute-upstream/) {{% /capture %}} diff --git a/update-imported-docs/reference.yml b/update-imported-docs/reference.yml index f674e3300eaf0..8e8702f350142 100644 --- a/update-imported-docs/reference.yml +++ b/update-imported-docs/reference.yml @@ -8,7 +8,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.14 + git checkout release-1.16 make generated_files cp -L -R vendor $GOPATH/src rm -r vendor @@ -36,25 +36,25 @@ repos: - src: gen-compdocs/build/kubeadm*.md dst: content/en/docs/reference/setup-tools/kubeadm/generated/ -- name: federation - remote: https://github.com/kubernetes/federation.git +#- name: federation +# remote: https://github.com/kubernetes/federation.git # Change this to a release branch when federation has release branches. - branch: master - generate-command: hack/generate-docs.sh - files: - - src: docs/admin/federation-apiserver.md - dst: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md - - src: docs/admin/federation-controller-manager.md - dst: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md - - src: docs/admin/kubefed_init.md - dst: content/en/docs/reference/setup-tools/kubefed/kubefed_init.md - - src: docs/admin/kubefed_join.md - dst: content/en/docs/reference/setup-tools/kubefed/kubefed_join.md - - src: docs/admin/kubefed.md - dst: content/en/docs/reference/setup-tools/kubefed/kubefed.md - - src: docs/admin/kubefed_options.md - dst: content/en/docs/reference/setup-tools/kubefed/kubefed_options.md - - src: docs/admin/kubefed_unjoin.md - dst: content/en/docs/reference/setup-tools/kubefed/kubefed_unjoin.md - - src: docs/admin/kubefed_version.md - dst: content/en/docs/reference/setup-tools/kubefed/kubefed_version.md +# branch: master +# generate-command: hack/generate-docs.sh +# files: +# - src: docs/admin/federation-apiserver.md +# dst: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md +# - src: docs/admin/federation-controller-manager.md +# dst: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md +# - src: docs/admin/kubefed_init.md +# dst: content/en/docs/reference/setup-tools/kubefed/kubefed_init.md +# - src: docs/admin/kubefed_join.md +# dst: content/en/docs/reference/setup-tools/kubefed/kubefed_join.md +# - src: docs/admin/kubefed.md +# dst: content/en/docs/reference/setup-tools/kubefed/kubefed.md +# - src: docs/admin/kubefed_options.md +# dst: content/en/docs/reference/setup-tools/kubefed/kubefed_options.md +# - src: docs/admin/kubefed_unjoin.md +# dst: content/en/docs/reference/setup-tools/kubefed/kubefed_unjoin.md +# - src: docs/admin/kubefed_version.md +# dst: content/en/docs/reference/setup-tools/kubefed/kubefed_version.md diff --git a/update-imported-docs/update-imported-docs b/update-imported-docs/update-imported-docs index 2657621abd0d8..5d9dc39e8b7ab 100755 --- a/update-imported-docs/update-imported-docs +++ b/update-imported-docs/update-imported-docs @@ -25,9 +25,11 @@ def processLinks(content, remotePrefix, subPath): target.startswith("mailto:") or target.startswith("#")): if target.startswith("/"): - target = "/".join(remotePrefix, target[1:]) + targetList = remotePrefix, target[1:] + target = "/".join(targetList) else: - target = "/".join(remotePrefix, subPath, target) + targetList = remotePrefix, subPath, target + target = "/".join(targetList) return "[%s](%s)" % (ankor, target) @@ -41,6 +43,25 @@ def processLinks(content, remotePrefix, subPath): return content +def processKubectlLinks(content): + """Update markdown links found in the SeeAlso section of kubectl page. + Example:[kubectl annotate](/docs/reference/generated/kubectl/kubectl-commands#annotate) + """ + def analyze(matchObj): + ankor = matchObj.group('ankor') + target = matchObj.group('target') + if (target.endswith(".md") and target.startswith("kubectl")): + ankorList = ankor.split("kubectl ") + target = "/docs/reference/generated/kubectl/kubectl-commands" + "#" + ankorList[1] + return "[%s](%s)" % (ankor, target) + + # Links are in the form '[text](url)' + linkRegex = re.compile(r"\[(?P.*)\]\((?P.*?)\)") + content = re.sub(linkRegex, analyze, content) + + return content + + def processFile(src, dst, repoPath, repoDir, rootDir, genAbsoluteLinks): """Process a file element. @@ -78,6 +99,9 @@ def processFile(src, dst, repoPath, repoDir, rootDir, genAbsoluteLinks): srcDir = os.path.dirname(src) remotePrefix = repoPath + "/tree/master" content = processLinks(content, remotePrefix, srcDir) + if dst.endswith("kubectl.md"): + print("Processing kubectl links") + content = processKubectlLinks(content) dstFile.write(content) except Exception as ex: print("[Error] failed in writing target file '%s': %s"