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 db6182341a25d..b4f03c1e33792 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-components.md @@ -116,136 +116,83 @@ need to work with someone who can set the label and milestone for you. ## Overview of update-imported-docs -The `update-imported-docs` tool performs these steps: - -1. Clone the `kubernetes/kubernetes` repository. -1. Run several scripts under `kubernetes/kubernetes/hack`. These scripts - generate Markdown files and place the files under `kubernetes/kubernetes/docs`. -1. Copy the generated Markdown files to a local clone of the `kubernetes/website` - repository under `kubernetes/website/docs/reference/generated`. -1. Clone the `kubernetes/federation` repository. -1. Run several scripts under `kubernetes/federation/hack`. These scripts - generate Markdown files and place the files under `kubernetes/federation/docs`. -1. Copy the generated Markdown files to a local clone of the `kubernetes/website` - repository under `kubernetes/website/docs/reference/generated`. - -After the Markdown files are in your local clone of the `kubernetes/website` +The website repository contains a `update-imported-docs` tool under the +`kubernetes/website/update-imported-docs/` directory that 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`. +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. + +When the Markdown files are in your local clone of the `kubernetes/website` repository, you can submit them in a [pull request](https://kubernetes.io/docs/home/contribute/create-pull-request/) to `kubernetes/website`. -## Setting the branch +## Customizing the config file -Open `/update-imported-docs/config.yaml` for editing. - -Set the value of `branch` to the Kubernetes release that you want to document. -For example, if you want to generate docs for the Kubernetes 1.9 release, -set `branch` to `release-1.9`. +Open `/update-imported-docs/reference.yaml` for editing. +Do not change the content for the `generate-command` entry unless you undertand +what it is doing and need to change the specified release branch. ```shell repos: -- name: kubernetes - remote: https://github.com/kubernetes/kubernetes.git - branch: release-1.9 +- name: reference-docs + remote: https://github.com/kubernetes-incubator/reference-docs.git + # This and the generate-command below needs a change when reference-docs has + # branches properly defined + branch: master + generate-command: | + cd $GOPATH + git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes + cd src/k8s.io/kubernetes + git checkout release-1.11 + make generated_files + cp -L -R vendor $GOPATH/src + rm -r vendor + cd $GOPATH + go get -v github.com/kubernetes-incubator/reference-docs/gen-compdocs + cd src/github.com/kubernetes-incubator/reference-docs/ + make comp ``` -## Setting sources and destinations - -The `update-imported-docs` tool uses `src` and `dst` fields -in `config.yaml` to know which files to copy from the `kubernetes/kubernetes` -repository and where to place those files in the `kubernetes/website` -repository. +The `update-imported-docs` tool uses `src` and `dst` fields in a configuration +to decide the source and target location for doc files to be copied. +For example: -For example, suppose you want the tool to copy the `kube-apiserver.md` file -from the `docs/admin` directory of the `kubernetes/kubernetes` repository -to the `docs/reference/generated/` directory of the `kubernetes/website` -repository. Then you would include a `src` and `dst` in your `config.yaml` -file like this: - -```shell +```yaml repos: -- name: kubernetes - remote: https://github.com/kubernetes/kubernetes.git - branch: release-1.9 +- name: reference-docs + remote: https://github.com/kubernetes-incubator/reference-docs.git files: - - src: docs/admin/kube-apiserver.md - dst: docs/reference/generated/kube-apiserver.md + - src: gen-compdocs/build/kube-apiserver.md + dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md ... ``` -The configuration is similar for files in the `kubernetes/federation` -repository. Here's an example that configures the tool to copy `kubefed_init.md` -from the `docs/admin` directory of the `kubernetes/federation` repository -to the `docs/reference/generated` directory of the `kubernetes/website` repository: +Note that when there are many files to be copied from the same source directory +to the same destination directory, you can use wildcards in the value given to +`src` and you can just provide the directory name as the value for `dst`. +For example: ```shell -- name: federation - remote: https://github.com/kubernetes/federation.git -# # Change this to a release branch when federation has release branches. - branch: master files: - - src: docs/admin/kubefed_init.md - dst: docs/reference/generated/kubefed_init.md - ... + - src: gen-compdocs/build/kubeadm*.md + dst: content/en/docs/reference/setup-tools/kubeadm/generated/ ``` -Here's an example a `config.yaml` file that shows the sources and -destinations of all the Markdown files that were generated and copied -by the `update-imported-docs` tool at the beginning of the Kubernetes -1.9 release. - -```shell -repos: -- name: kubernetes - remote: https://github.com/kubernetes/kubernetes.git - branch: release-1.9 - files: - - src: docs/admin/cloud-controller-manager.md - dst: docs/reference/generated/cloud-controller-manager.md - - src: docs/admin/kube-apiserver.md - dst: docs/reference/generated/kube-apiserver.md - - src: docs/admin/kube-controller-manager.md - dst: docs/reference/generated/kube-controller-manager.md - - src: docs/admin/kubelet.md - dst: docs/reference/generated/kubelet.md - - src: docs/admin/kube-proxy.md - dst: docs/reference/generated/kube-proxy.md - - src: docs/admin/kube-scheduler.md - dst: docs/reference/generated/kube-scheduler.md - - src: docs/user-guide/kubectl/kubectl.md - dst: docs/reference/generated/kubectl/kubectl.md -- name: federation - remote: https://github.com/kubernetes/federation.git -# # Change this to a release branch when federation has release branches. - branch: master - files: - - src: docs/admin/federation-apiserver.md - dst: docs/reference/generated/federation-apiserver.md - - src: docs/admin/federation-controller-manager.md - dst: docs/reference/generated/federation-controller-manager.md - - src: docs/admin/kubefed_init.md - dst: docs/reference/generated/kubefed_init.md - - src: docs/admin/kubefed_join.md - dst: docs/reference/generated/kubefed_join.md - - src: docs/admin/kubefed.md - dst: docs/reference/generated/kubefed.md - - src: docs/admin/kubefed_options.md - dst: docs/reference/generated/kubefed_options.md - - src: docs/admin/kubefed_unjoin.md - dst: docs/reference/generated/kubefed_unjoin.md - - src: docs/admin/kubefed_version.md - dst: docs/reference/generated/kubefed_version.md - ``` - ## Running the update-imported-docs tool -Now that your `config.yaml` file contains your sources and destinations, -you can run the `update-imported-docs` tool: +After having reviewed and/or customized the `reference.yaml` file, you can run +the `update-imported-docs` tool: ```shell -cd -go get ./update-imported-docs -go run update-imported-docs/update-imported-docs.go +cd /update-imported-docs +./update-imported-docs reference.yml ``` ## Adding and committing changes in kubernetes/website @@ -263,21 +210,15 @@ might look like this: ```shell ... - modified: docs/reference/generated/cloud-controller-manager.md - modified: docs/reference/generated/federation-apiserver.md - modified: docs/reference/generated/federation-controller-manager.md - modified: docs/reference/generated/kube-apiserver.md - modified: docs/reference/generated/kube-controller-manager.md - modified: docs/reference/generated/kube-proxy.md - modified: docs/reference/generated/kube-scheduler.md - modified: docs/reference/generated/kubectl/kubectl.md - modified: docs/reference/generated/kubefed.md - modified: docs/reference/generated/kubefed_init.md - modified: docs/reference/generated/kubefed_join.md - modified: docs/reference/generated/kubefed_options.md - modified: docs/reference/generated/kubefed_unjoin.md - modified: docs/reference/generated/kubefed_version.md - modified: docs/reference/generated/kubelet.md + + 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 +... ``` Run `git add` and `git commit` to commit the files. @@ -303,4 +244,3 @@ topics will be visible in the {{% /capture %}} - diff --git a/content/en/docs/contribute/start.md b/content/en/docs/contribute/start.md index 22dcdae19478a..1233becf817ff 100644 --- a/content/en/docs/contribute/start.md +++ b/content/en/docs/contribute/start.md @@ -28,7 +28,7 @@ The Kubernetes documentation is written in Markdown and processed and deployed using Hugo. The source is in Github at [https://github.com/kubernetes/website](https://github.com/kubernetes/website). Most of the documentation source is stored in `/content/en/docs/`. Some of the -reference documentation is automatically generated from scripts, mostly in the +reference documentation is automatically generated from scripts in the `update-imported-docs/` directory. You can file issues, edit content, and review changes from others, all from the diff --git a/update-imported-docs/README.md b/update-imported-docs/README.md index 27c5057a2465f..ffd0480217d61 100644 --- a/update-imported-docs/README.md +++ b/update-imported-docs/README.md @@ -1,12 +1,15 @@ # Update imported docs -This script updates the target files generated from other repos listed in the file, which is specified as the command line argument. +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. ## Requirements Imported docs must follow these guidelines: -1. Be listed somewhere in the `/_data/imported.yml` table of contents file. +1. Adhere to the [Documentation Style Guide](/docs/home/contribute/style-guide/). + 1. Have `title` defined in the front matter. For example: ``` @@ -16,49 +19,36 @@ Imported docs must follow these guidelines: Rest of the .md file... ``` +1. Be listed somewhere in a file under the `data` subdirectory, for example, + the `data/imported.yml` file. -1. Adhere to the [Documentation Style Guide](/docs/home/contribute/style-guide/). - -## Usage - -From within this directory, run the following command: +1. Make sure the `PyYAML` package is installed: ``` -+./update-imported-docs-[linux|macos] +sudo apt-get install python-pip +pip install PyYAML ``` -The output should look similar to the following: - -``` -Website root directory: /Users/someuser/git/kubernetes-website - - * * * - -Cloning repo "community"... +## Usage - * * * +From within this directory, run the following command: -Docs imported! Run 'git add .' 'git commit -m ' and 'git push' to upload them. +``` ++./update-imported-docs ``` -## Config file format +where `` can be any YAML configuration file in this directory. -Each config file may contain multiple repos, which will be imported together. You should modify the corresponding `update-imported-docs/` file to reflect the desired `src` and `dst` paths. +## Configuration file format -You may also create new config files for different groups of documents to import. The following is an example of the YAML 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: kubernetes #tmp directory name - remote: https://github.com/kubernetes/kubernetes.git - branch: release-1.9 - generate-command: hack/generate-docs.sh #optional command to run - files: - - src: docs/admin/cloud-controller-manager.md - dst: docs/reference/generated/cloud-controller-manager.md - - src: docs/admin/kube-apiserver.md - dst: docs/reference/generated/kube-apiserver.md -- name: community #tmp directory name +- name: community remote: https://github.com/kubernetes/community.git branch: master files: @@ -68,8 +58,11 @@ repos: dst: docs/imported/community/guide.md ``` -Note: `generate-command` is an optional entry, which can be used to run a given command to auto-generate the docs from within that repo. +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` value to `true`. You can see an example of this in [`community.yml`](community.yml). +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 +[`community.yml`](community.yml). diff --git a/update-imported-docs/reference.yml b/update-imported-docs/reference.yml index f741379020dd9..43745288bb7ea 100644 --- a/update-imported-docs/reference.yml +++ b/update-imported-docs/reference.yml @@ -1,186 +1,44 @@ repos: -- name: kubernetes - remote: https://github.com/kubernetes/kubernetes.git - branch: release-1.11 - generate-command: hack/generate-docs.sh +- name: reference-docs + remote: https://github.com/kubernetes-incubator/reference-docs.git + # This and the generate-command below needs a change when reference-docs has + # branches properly defined + branch: master + generate-command: | + cd $GOPATH + git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes + cd src/k8s.io/kubernetes + git checkout release-1.11 + make generated_files + cp -L -R vendor $GOPATH/src + rm -r vendor + cd $GOPATH + go get -v github.com/kubernetes-incubator/reference-docs/gen-compdocs + cd src/github.com/kubernetes-incubator/reference-docs/ + make comp + files: - - src: docs/admin/cloud-controller-manager.md - dst: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md - - src: docs/admin/kube-apiserver.md - dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md - - src: docs/admin/kube-controller-manager.md - dst: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md - - src: docs/admin/kubelet.md - dst: content/en/docs/reference/command-line-tools-reference/kubelet.md - - src: docs/admin/kube-proxy.md - dst: content/en/docs/reference/command-line-tools-reference/kube-proxy.md - - src: docs/admin/kube-scheduler.md - dst: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md - - src: docs/user-guide/kubectl/kubectl.md - dst: content/en/docs/reference/kubectl/kubectl.md - - src: docs/admin/kubeadm_alpha.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha.md - - src: docs/admin/kubeadm_alpha_phase_addon_all.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_addon_all.md - - src: docs/admin/kubeadm_alpha_phase_addon_coredns.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_addon_coredns.md - - src: docs/admin/kubeadm_alpha_phase_addon_kube-proxy.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_addon_kube-proxy.md - - src: docs/admin/kubeadm_alpha_phase_addon.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_addon.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token_all.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token_all.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token_cluster-info.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token_cluster-info.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token_create.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token_create.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token_node_allow-auto-approve.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token_node_allow-auto-approve.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token_node_allow-post-csrs.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token_node_allow-post-csrs.md - - src: docs/admin/kubeadm_alpha_phase_bootstrap-token_node.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_bootstrap-token_node.md - - src: docs/admin/kubeadm_alpha_phase_certs_all.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_all.md - - src: docs/admin/kubeadm_alpha_phase_certs_apiserver-etcd-client.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_apiserver-etcd-client.md - - src: docs/admin/kubeadm_alpha_phase_certs_apiserver-kubelet-client.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_apiserver-kubelet-client.md - - src: docs/admin/kubeadm_alpha_phase_certs_apiserver.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_apiserver.md - - src: docs/admin/kubeadm_alpha_phase_certs_ca.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_ca.md - - src: docs/admin/kubeadm_alpha_phase_certs_etcd-ca.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_etcd-ca.md - - src: docs/admin/kubeadm_alpha_phase_certs_etcd-healthcheck-client.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_etcd-healthcheck-client.md - - src: docs/admin/kubeadm_alpha_phase_certs_etcd-peer.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_etcd-peer.md - - src: docs/admin/kubeadm_alpha_phase_certs_etcd-server.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_etcd-server.md - - src: docs/admin/kubeadm_alpha_phase_certs_front-proxy-ca.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_front-proxy-ca.md - - src: docs/admin/kubeadm_alpha_phase_certs_front-proxy-client.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_front-proxy-client.md - - src: docs/admin/kubeadm_alpha_phase_certs.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs.md - - src: docs/admin/kubeadm_alpha_phase_certs_sa.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_certs_sa.md - - src: docs/admin/kubeadm_alpha_phase_controlplane_all.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_controlplane_all.md - - src: docs/admin/kubeadm_alpha_phase_controlplane_apiserver.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_controlplane_apiserver.md - - src: docs/admin/kubeadm_alpha_phase_controlplane_controller-manager.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_controlplane_controller-manager.md - - src: docs/admin/kubeadm_alpha_phase_controlplane.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_controlplane.md - - src: docs/admin/kubeadm_alpha_phase_controlplane_scheduler.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_controlplane_scheduler.md - - src: docs/admin/kubeadm_alpha_phase_etcd_local.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_etcd_local.md - - src: docs/admin/kubeadm_alpha_phase_etcd.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_etcd.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig_admin.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig_admin.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig_all.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig_all.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig_controller-manager.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig_controller-manager.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig_kubelet.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig_kubelet.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig_scheduler.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig_scheduler.md - - src: docs/admin/kubeadm_alpha_phase_kubeconfig_user.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubeconfig_user.md - - src: docs/admin/kubeadm_alpha_phase_kubelet_config_download.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet_config_download.md - - src: docs/admin/kubeadm_alpha_phase_kubelet_config_enable-dynamic.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet_config_enable-dynamic.md - - src: docs/admin/kubeadm_alpha_phase_kubelet_config.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet_config.md - - src: docs/admin/kubeadm_alpha_phase_kubelet_config_upload.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet_config_upload.md - - src: docs/admin/kubeadm_alpha_phase_kubelet_config_write-to-disk.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet_config_write-to-disk.md - - src: docs/admin/kubeadm_alpha_phase_kubelet.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet.md - - src: docs/admin/kubeadm_alpha_phase_kubelet_write-env-file.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_kubelet_write-env-file.md - - src: docs/admin/kubeadm_alpha_phase_mark-master.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_mark-master.md - - src: docs/admin/kubeadm_alpha_phase.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase.md - - src: docs/admin/kubeadm_alpha_phase_preflight_master.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_preflight_master.md - - src: docs/admin/kubeadm_alpha_phase_preflight.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_preflight.md - - src: docs/admin/kubeadm_alpha_phase_preflight_node.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_preflight_node.md - - src: docs/admin/kubeadm_alpha_phase_selfhosting_convert-from-staticpods.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_selfhosting_convert-from-staticpods.md - - src: docs/admin/kubeadm_alpha_phase_selfhosting.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_selfhosting.md - - src: docs/admin/kubeadm_alpha_phase_upload-config.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_alpha_phase_upload-config.md - - src: docs/admin/kubeadm_completion.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_completion.md - - src: docs/admin/kubeadm_config_images_list.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_images_list.md - - src: docs/admin/kubeadm_config_images.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_images.md - - src: docs/admin/kubeadm_config_images_pull.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_images_pull.md - - src: docs/admin/kubeadm_config.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config.md - - src: docs/admin/kubeadm_config_migrate.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_migrate.md - - src: docs/admin/kubeadm_config_print-default.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_print-default.md - - src: docs/admin/kubeadm_config_upload_from-file.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_upload_from-file.md - - src: docs/admin/kubeadm_config_upload_from-flags.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_upload_from-flags.md - - src: docs/admin/kubeadm_config_upload.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_upload.md - - src: docs/admin/kubeadm_config_view.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_config_view.md - - src: docs/admin/kubeadm_init.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_init.md - - src: docs/admin/kubeadm_join.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_join.md - - src: docs/admin/kubeadm_reset.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_reset.md - - src: docs/admin/kubeadm_token_create.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_token_create.md - - src: docs/admin/kubeadm_token_delete.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_token_delete.md - - src: docs/admin/kubeadm_token_generate.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_token_generate.md - - src: docs/admin/kubeadm_token_list.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_token_list.md - - src: docs/admin/kubeadm_token.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_token.md - - src: docs/admin/kubeadm_upgrade_apply.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade_apply.md - - src: docs/admin/kubeadm_upgrade_diff.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade_diff.md - - src: docs/admin/kubeadm_upgrade.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade.md - - src: docs/admin/kubeadm_upgrade_node_config.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade_node_config.md - - src: docs/admin/kubeadm_upgrade_node.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade_node.md - - src: docs/admin/kubeadm_upgrade_plan.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_upgrade_plan.md - - src: docs/admin/kubeadm_version.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_version.md + - src: gen-compdocs/build/cloud-controller-manager.md + dst: content/en/docs/reference/command-line-tools-reference/ + - src: gen-compdocs/build/kube-apiserver.md + dst: content/en/docs/reference/command-line-tools-reference/ + - src: gen-compdocs/build/kube-controller-manager.md + dst: content/en/docs/reference/command-line-tools-reference/ + # We have problems generating docs for kubelet, it is done manually now + # - src: gen-compdocs/build/kubelet.md + # dst: content/en/docs/reference/command-line-tools-reference/ + - src: gen-compdocs/build/kube-proxy.md + dst: content/en/docs/reference/command-line-tools-reference/ + - src: gen-compdocs/build/kube-scheduler.md + dst: content/en/docs/reference/command-line-tools-reference/ + - src: gen-compdocs/build/kubectl.md + dst: content/en/docs/reference/kubectl/ + - src: gen-compdocs/build/kubeadm*.md + dst: content/en/docs/reference/setup-tools/kubeadm/generated/ + - name: federation remote: https://github.com/kubernetes/federation.git -# # Change this to a release branch when federation has release branches. + # Change this to a release branch when federation has release branches. branch: master generate-command: hack/generate-docs.sh files: @@ -189,14 +47,14 @@ repos: - 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 + 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 + 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 + 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 + 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 + 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 new file mode 100755 index 0000000000000..2657621abd0d8 --- /dev/null +++ b/update-imported-docs/update-imported-docs @@ -0,0 +1,158 @@ +#!/usr/bin/env python + +import glob +import os +import re +import shutil +import subprocess +import sys + +try: + import yaml +except Exception: + print("Please ensure PyYAML package is installed. This can be done, for " + "example, by executing the following command:\n\n" + " pip install pyyaml\n") + sys.exit(-1) + + +def processLinks(content, remotePrefix, subPath): + """Process markdown links found in the docs.""" + def analyze(matchObj): + ankor = matchObj.group('ankor') + target = matchObj.group('target') + if not (target.startswith("https://") or + target.startswith("mailto:") or + target.startswith("#")): + if target.startswith("/"): + target = "/".join(remotePrefix, target[1:]) + else: + target = "/".join(remotePrefix, subPath, target) + + return "[%s](%s)" % (ankor, target) + + # Links are in the form '[text](url)' + linkRegex = re.compile(r"\[(?P.*)\]\((?P.*)\)") + content = re.sub(linkRegex, analyze, content) + + h1Regex = re.compile("^(# .*)?\n") + content = re.sub(h1Regex, "", content) + + return content + + +def processFile(src, dst, repoPath, repoDir, rootDir, genAbsoluteLinks): + """Process a file element. + + :param src: A string containing the relative path of a source file. The + string may contain wildcard characters such as '*' or '?'. + :param dst: The path for the destination file. The string can be a + directory name or a file name. + """ + pattern = os.path.join(repoDir, repoPath, src) + dstPath = os.path.join(rootDir, dst) + + for src in glob.glob(pattern): + # we don't dive into subdirectories + if not os.path.isfile(src): + print("[Error] skipping non-regular path %s" % src) + continue + + content = "" + try: + with open(src, "r") as srcFile: + content = srcFile.read() + except Exception as ex: + print("[Error] failed in reading source file: " + str(ex)) + continue + + dst = dstPath + if dstPath.endswith("/"): + baseName = os.path.basename(src) + dst = os.path.join(dst, baseName) + + try: + print("Writing doc: " + dst) + with open(dst, "w") as dstFile: + if genAbsoluteLinks: + srcDir = os.path.dirname(src) + remotePrefix = repoPath + "/tree/master" + content = processLinks(content, remotePrefix, srcDir) + dstFile.write(content) + except Exception as ex: + print("[Error] failed in writing target file '%s': %s" + "" % (dst, str(ex))) + continue + + +def main(): + """The main entry of the program.""" + if len(sys.argv) < 2: + print("[Error] Please specify a config file") + return -1 + + configFile = sys.argv[1] + currDir = os.path.dirname(__file__) + rootDir = os.path.realpath(os.path.join(currDir, '..')) + + try: + configData = yaml.load(open(configFile, 'r')) + except Exception as ex: + print("[Error] failed in loading config file - %s" % str(ex)) + return -2 + + os.chdir(rootDir) + workDir = "/tmp/update_docs" + shutil.rmtree(workDir, True) + os.mkdir(workDir, 0750) + + for repo in configData["repos"]: + if "name" not in repo: + print("[Error] repo missing name") + continue + repoName = repo["name"] + + if "remote" not in repo: + print("[Error] repo '%s' missing repo path" % repoName) + continue + repoRemote = repo["remote"] + + remoteRegex = re.compile(r"^https://(?P.*)\.git$") + matches = remoteRegex.search(repoRemote) + if not matches: + print("[Error] repo path for '%s' is invalid" % repoName) + continue + + repoPath = os.path.join("src", matches.group('prefix')) + os.chdir(workDir) + print("Cloning repo %s..." % repoName) + cmd = "git clone --depth=1 -b {0} {1} {2}".format( + repo["branch"], repoRemote, repoPath) + res = subprocess.call(cmd, shell=True) + if res != 0: + print("[Error] failed in cloning repo '%s'" % repoName) + continue + + os.chdir(repoPath) + if "generate-command" in repo: + genCmd = repo["generate-command"] + genCmd = "export GOPATH=" + workDir + "\n" + genCmd + print("Generating docs for %s with %s" % (repoName, genCmd)) + res = subprocess.call(genCmd, shell=True) + if res != 0: + print("[Error] failed in generating docs for '%s'" % repoName) + continue + + os.chdir(rootDir) + for f in repo["files"]: + processFile(f['src'], f['dst'], repoPath, workDir, rootDir, + "gen-absolute-links" in repo) + + print("Completed docs update. Now run the following command to commit:\n\n" + " git add .\n" + " git commit -m \n" + " git push\n") + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/update-imported-docs/update-imported-docs-linux b/update-imported-docs/update-imported-docs-linux deleted file mode 100755 index a8a230c2b8c5c..0000000000000 Binary files a/update-imported-docs/update-imported-docs-linux and /dev/null differ diff --git a/update-imported-docs/update-imported-docs-macos b/update-imported-docs/update-imported-docs-macos deleted file mode 100755 index 3bf65a5a0b263..0000000000000 Binary files a/update-imported-docs/update-imported-docs-macos and /dev/null differ diff --git a/update-imported-docs/update-imported-docs.go b/update-imported-docs/update-imported-docs.go deleted file mode 100644 index 46912150d468b..0000000000000 --- a/update-imported-docs/update-imported-docs.go +++ /dev/null @@ -1,213 +0,0 @@ -package main - -import ( - "bufio" - "fmt" - "io/ioutil" - "os" - "os/exec" - "path" - "path/filepath" - "regexp" - "strings" - "github.com/ghodss/yaml" -) - -func main() { - - //get command line arguments without executable - clArgs := os.Args[1:] - - //check that an argument has been passed in - if len(clArgs) == 0 { - fmt.Fprintf(os.Stderr, "Please specify a config file as a command line argument.\n") - os.Exit(1) - } - configFile := clArgs[0] - - //get directory of executable - ex, err := os.Executable() - checkError(err) - exPath := filepath.Dir(ex) //file path of updated-imported-docs executable - suffix := filepath.Base(exPath) //should be "updated-imported-docs" - - //check if suffix is "updated-imported-docs" - if suffix != "update-imported-docs" { - fmt.Fprintf(os.Stderr, "Instead of `go run update-imported-docs.go `, use the compiled binary `./update-imported-docs `\n") - os.Exit(1) - } - - //set root directory of website - websiteRepo := filepath.Clean(strings.TrimSuffix(exPath,suffix)) //path of parent directory - fmt.Fprintf(os.Stdout, "Website root directory: %s\n", websiteRepo) - - //read config.yaml file specified by first command line argument - content, err := ioutil.ReadFile(configFile) - if err != nil { - fmt.Fprintf(os.Stderr, "Error when reading file: %v\n", err) - os.Exit(1) - } - - //convert contents of config.yml file into a map - var config map[string]interface{} - err = yaml.Unmarshal(content, &config) - if err != nil { - fmt.Fprintf(os.Stderr, "Error when unmarshal the config file: %v\n", err) - os.Exit(1) - } - - //change working directory to website root - err = os.Chdir(websiteRepo) - checkError(err) - - //clean out temp directory - tmpDir := "/tmp/update_docs" - os.RemoveAll(tmpDir) - os.Mkdir(tmpDir, 0750) - - // Match the content between 2 `---` - // It mostly have something like: - // --- - // title: *** - // notile: *** - // --- - titleRegex := regexp.MustCompile("^---\ntitle:(.*\n)*?---\n") - - // To extract repo path prefix from `remote` - remoteGitRegex := regexp.MustCompile("(https://.*)\\.git$") - - //execute for each repo - repos := config["repos"].([]interface{}) - for _, repo := range repos { - err = os.Chdir(tmpDir) - checkError(err) - - //get config info for repo, clone repo locally - r := repo.(map[string]interface{}) - repoName := r["name"].(string) - remotePathMatch := remoteGitRegex.FindAllStringSubmatch(r["remote"].(string), -1) - if (len(remotePathMatch) == 0) { - fmt.Fprintf(os.Stderr, "\n\t\t\t!\t!\t!\n\nInvalid remote path %q. Schema should look like: https://.git\n", r["remote"].(string)) - os.Exit(1) - } - remotePrefix := fmt.Sprintf("%s/tree/master", remotePathMatch[0][1]) - - cmd := "git" - args := []string{"clone", "--depth=1", "-b", r["branch"].(string), r["remote"].(string), repoName} - fmt.Fprintf(os.Stdout, "\n\t\t\t*\t*\t*\n\nCloning repo %q...\n", repoName) - if err := exec.Command(cmd, args...).Run(); err != nil { - fmt.Fprintf(os.Stderr, "\n\t\t\t!\t!\t!\n\nError when cloning repo %q: %v\n", repoName, err) - os.Exit(1) - } - - err = os.Chdir(repoName) - checkError(err) - - //if generate-command is specified in the repo config, - //run the command for that repo, e.g. "hack/generate-docs.sh" - if r["generate-command"] != nil { - genCmd := r["generate-command"].(string) - - fmt.Fprintf(os.Stdout, "Generating docs for repo %q with %q...\n\n", repoName, genCmd) - cmd := exec.Command(genCmd) - cmdReader, err := cmd.StdoutPipe() - if err != nil { - fmt.Fprintf(os.Stderr, "\n\t\t\t!\t!\t!\n\nError when generating docs for repo %q: %v\n", repoName, err) - os.Exit(1) - } - - //display running output of generate command - scanner := bufio.NewScanner(cmdReader) - go func() { - for scanner.Scan() { - fmt.Printf("generator output | %s\n", scanner.Text()) - } - }() - - err = cmd.Start() - if err != nil { - fmt.Fprintln(os.Stderr, "Error starting %q command\n", genCmd, err) - os.Exit(1) - } - - err = cmd.Wait() - if err != nil { - fmt.Fprintln(os.Stderr, "Error waiting for %q command\n", genCmd, err) - os.Exit(1) - } - - } - - //copy and rename files from src -> dst specified in config - err = os.Chdir(websiteRepo) - checkError(err) - files := r["files"].([]interface{}) - for _, file := range files { - f := file.(map[string]interface{}) - src := f["src"].(string) - dst := f["dst"].(string) - srcDir := filepath.Dir(src) - absSrc, err := filepath.Abs(path.Join(tmpDir, repoName, src)) - checkError(err) - absDst, err := filepath.Abs(dst) - checkError(err) - // Ignore the error if the old file is not found/ - content, _ := ioutil.ReadFile(absDst) - titleBlock := titleRegex.Find(content) - content, err = ioutil.ReadFile(absSrc) - checkError(err) - - // Write to new output file - dstFile, err := os.OpenFile(absDst, os.O_RDWR|os.O_CREATE, 0755) - checkError(err) - defer dstFile.Close() - _, err = dstFile.Write(titleBlock) - checkError(err) - - // Process content if necessary - if r["gen-absolute-links"] != nil { - content = processLinks(content, remotePrefix, srcDir) - } - _, err = dstFile.Write(content) - checkError(err) - dstFile.Sync() - } - } - fmt.Fprintf(os.Stdout, "\n\t\t\t*\t*\t*\n\nDocs imported! Run 'git add .' 'git commit -m ' and 'git push' to upload them.\n") -} - -// -func processLinks(content []byte, remotePrefix string, subPath string) []byte { - // To catch anything of the form [text](url) - linkRegex := regexp.MustCompile("(\\[.+?\\])\\(([^\\s\\)]+)\\)") - // Regexes to skip - absUrlRegex := regexp.MustCompile("https*://") - mailRegex := regexp.MustCompile("mailto:") - - processedContent := linkRegex.ReplaceAllFunc(content, func(b []byte) []byte { - if (absUrlRegex.Match(b) || mailRegex.Match(b)) { - return b // no processing needed - } - match := linkRegex.FindAllStringSubmatch(string(b), -1) - url := match[0][2] - if url[0] == '#' { // link on current page - return b - } else if url[0] == '/' { // link at root of repo - return []byte(fmt.Sprintf("%s(%s/%s)", match[0][1], remotePrefix, url[1:])) - } else { // link relative to current page - return []byte(fmt.Sprintf("%s(%s/%s/%s)", match[0][1], remotePrefix, subPath, url)) - } - }) - - h1Regex := regexp.MustCompile("^(# .*)?\n") - processedContent = h1Regex.ReplaceAll(processedContent, []byte("")) - - return processedContent -} - -func checkError(err error) { - if err != nil { - fmt.Fprintln(os.Stderr, err) - os.Exit(1) - } -}