From 520eacac5bd5ba85f5a8ec4e869fe12c56f0f2a2 Mon Sep 17 00:00:00 2001 From: Priyanka Behera Date: Wed, 13 Nov 2024 00:15:21 +0530 Subject: [PATCH 1/2] Add visuals to README.md --- README.md | 199 +++++++++++++++++++++++++++--------------------------- 1 file changed, 101 insertions(+), 98 deletions(-) diff --git a/README.md b/README.md index 7ad7457d45ab1..9179fdce155ac 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,29 @@ [![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-main-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest) -This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad that you want to contribute! - -- [Contributing to the docs](#contributing-to-the-docs) -- [Localization READMEs](#localization-readmes) +Welcome! This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad you're interested in contributing. + +## Table of Contents +1. [Using This Repository](#using-this-repository) +2. [Prerequisites](#prerequisites) +3. [Running the Website](#running-the-website) +4. [Building the API Reference Pages](#building-the-api-reference-pages) +5. [Troubleshooting](#troubleshooting) +6. [Get Involved with SIG Docs](#get-involved-with-sig-docs) +7. [Contributing to the Docs](#contributing-to-the-docs) +8. [Localization READMEs](#localization-readmes) +9. [Code of Conduct](#code-of-conduct) +10.[Thank You!](#thank-you) + +--- ## Using this repository -You can run the website locally using [Hugo (Extended version)](https://gohugo.io/), or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website. +Run the website locally using [Hugo (Extended version)](https://gohugo.io/), or in a container runtime (recommend for deployment consistency with the live site). ## Prerequisites -To use this repository, you need the following installed locally: +To use this repository, you'll need: - [npm](https://www.npmjs.com/) - [Go](https://go.dev/) @@ -21,145 +32,131 @@ To use this repository, you need the following installed locally: - A container runtime, like [Docker](https://www.docker.com/). > [!NOTE] -Make sure to install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L11) file. +Ensure you install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L11). -Before you start, install the dependencies. Clone the repository and navigate to the directory: +## Running the Website -```bash -git clone https://github.com/kubernetes/website.git -cd website -``` +**Initial Setup** -The Kubernetes website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme). Even if you plan to run the website in a container, we strongly recommend pulling in the submodule and other development dependencies by running the following: + 1. **Clone the Repository**: -### Windows + ```bash + git clone https://github.com/kubernetes/website.git + cd website + ``` -```powershell -# fetch submodule dependencies -git submodule update --init --recursive --depth 1 -``` + >[!Note] + The Kubernetes website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme).So, pulling in submodule is strongly recommended. -### Linux / other Unix + 2. **Initialize Submodules and Dependencies**: -```bash -# fetch submodule dependencies -make module-init -``` + - **Windows**: -## Running the website using a container + ```bash + git submodule update --init --recursive --depth 1 + ``` -To build the site in a container, run the following: + - **Linux / Unix**: -```bash -# You can set $CONTAINER_ENGINE to the name of any Docker-like container tool -make container-serve -``` + ```bash + make module-init + ``` -If you see errors, it probably means that the hugo container did not have enough computing resources available. To solve it, increase the amount of allowed CPU and memory usage for Docker on your machine ([MacOS](https://docs.docker.com/desktop/settings/mac/) and [Windows](https://docs.docker.com/desktop/settings/windows/)). +**Running using a container** -Open up your browser to to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh. + 1. **Build the site**: -## Running the website locally using Hugo + ```bash + # You can set $CONTAINER_ENGINE to the name of any Docker-like container tool + make container-serve + ``` + 2. Open in a browser to view the website. -To install dependencies, deploy and test the site locally, run: + >[!Note] + If you see errors, increase the amount of allowed CPU and memory usage for Docker on your machine ([MacOS](https://docs.docker.com/desktop/settings/mac/) and [Windows](https://docs.docker.com/desktop/settings/windows/)). -- For macOS and Linux +**Running Locally using Hugo** - ```bash - npm ci - make serve - ``` + To install dependencies, deploy and test the site: -- For Windows (PowerShell) + - **macOS/Linux**: - ```powershell - npm ci - hugo.exe server --buildFuture --environment development - ``` + ```bash + npm ci + make serve + ``` + + - **Windows (PowerShell)**: + + ```powershell + npm ci + hugo.exe server --buildFuture --environment development + ``` -This will start the local Hugo server on port 1313. Open up your browser to to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh. + Vist to see your changes. +--- -## Building the API reference pages -The API reference pages located in `content/en/docs/reference/kubernetes-api` are built from the Swagger specification, also known as OpenAPI specification, using . +### Updating API Reference Pages -To update the reference pages for a new Kubernetes release follow these steps: +The API reference pages are built from the Swagger (OpenAPI) specification using [gen-resourcesdocs](https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs). -1. Pull in the `api-ref-generator` submodule: +**Steps to Update for a New Kubernetes Release**: +1. **Pull in the api-ref-generator submodule**: ```bash git submodule update --init --recursive --depth 1 ``` -2. Update the Swagger specification: +2. **Update the Swagger specification**: ```bash curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json ``` -3. In `api-ref-assets/config/`, adapt the files `toc.yaml` and `fields.yaml` to reflect the changes of the new release. +3. **Update the configuration files** (`toc.yaml` and `fields.yaml`) in `api-ref-assets/config/` to reflect the new release. -4. Next, build the pages: +4. **Build the pages**: ```bash make api-reference ``` - You can test the results locally by building and serving the site from a container: +5. **Test locally by serving the site**: ```bash make container-serve ``` - In a web browser, go to to view the API reference. + View at: -5. When all changes of the new contract are reflected into the configuration files `toc.yaml` and `fields.yaml`, create a Pull Request with the newly generated API reference pages. +6. Once everything is updated, create a Pull Request with the new API reference pages. +--- ## Troubleshooting -### error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version - -Hugo is shipped in two set of binaries for technical reasons. The current website runs based on the **Hugo Extended** version only. In the [release page](https://github.com/gohugoio/hugo/releases) look for archives with `extended` in the name. To confirm, run `hugo version` and look for the word `extended`. - -### Troubleshooting macOS for too many open files - -If you run `make serve` on macOS and receive the following error: - -```bash -ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files -make: *** [serve] Error 1 -``` - -Try checking the current limit for open files: - -`launchctl limit maxfiles` - -Then run the following commands (adapted from ): +1. **TOCSS Error** + -This issue occurs if the Hugo Extended version isn’t installed. Verify it shows `extended` by running: -```shell -#!/bin/sh - -# These are the original gist links, linking to my gists now. -# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist -# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist - -curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist -curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist + ```bash + hugo version + ``` -sudo mv limit.maxfiles.plist /Library/LaunchDaemons -sudo mv limit.maxproc.plist /Library/LaunchDaemons + -In the [release page](https://github.com/gohugoio/hugo/releases) look for archives with `extended` in the name. -sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist -sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist +2. **Too Many Open Files(macOS)** + -Check the open file limit: + ```bash + launchctl limit maxfiles + ``` -sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist -``` + -Follow the [gist instructions](https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c) to increase the limit. -This works for Catalina as well as Mojave macOS. +--- ## Get involved with SIG Docs -Learn more about SIG Docs Kubernetes community and meetings on the [community page](https://github.com/kubernetes/community/tree/master/sig-docs#meetings). +Learn more about [SIG Doc](https://github.com/kubernetes/community/blob/master/sig-docs/README.md) and join the Kubernetes community on Slack. You can also reach the maintainers of this project at: @@ -167,15 +164,15 @@ You can also reach the maintainers of this project at: - [Get an invite for this Slack](https://slack.k8s.io/) - [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) -## Contributing to the docs +--- -You can click the **Fork** button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a _fork_. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it. +## Contributing to the Docs +Click the **Fork** button to create a copy of this repository in your GitHub account. Make any changes in your fork and, when ready, create a pull request. -Once your pull request is created, a Kubernetes reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request, **it is your responsibility to modify your pull request to address the feedback that has been provided to you by the Kubernetes reviewer.** +Once submitted, a Kubernetes reviewer will provide feedback. As the PR owner, you are responsible for modifying the PR as needed. -Also, note that you may end up having more than one Kubernetes reviewer provide you feedback or you may end up getting feedback from a Kubernetes reviewer that is different than the one initially assigned to provide you feedback. +> [!Note]: Multiple reviewers may provide feedback. Reviewers will try to respond promptly, but response time may vary. -Furthermore, in some cases, one of your reviewers might ask for a technical review from a Kubernetes tech reviewer when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances. For more information about contributing to the Kubernetes documentation, see: @@ -185,14 +182,18 @@ For more information about contributing to the Kubernetes documentation, see: - [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/) - [Introduction to Kubernetes Docs](https://www.youtube.com/watch?v=pprMgmNzDcw) -### New contributor ambassadors +--- + +**New contributor ambassadors** -If you need help at any point when contributing, the [New Contributor Ambassadors](https://kubernetes.io/docs/contribute/advanced/#serve-as-a-new-contributor-ambassador) are a good point of contact. These are SIG Docs approvers whose responsibilities include mentoring new contributors and helping them through their first few pull requests. The best place to contact the New Contributors Ambassadors would be on the [Kubernetes Slack](https://slack.k8s.io/). Current New Contributors Ambassadors for SIG Docs: +If you need help while contributing, the [New Contributor Ambassadors](https://kubernetes.io/docs/contribute/advanced/#serve-as-a-new-contributor-ambassador) are SIG Docs approvers who mentor new contributors. Contact them via [Kubernetes Slack](https://slack.k8s.io/). Current Ambassadors for SIG Docs: | Name | Slack | GitHub | | -------------------------- | -------------------------- | -------------------------- | | Sreeram Venkitesh | @sreeram.venkitesh | @sreeram-venkitesh | +--- + ## Localization READMEs | Language | Language | @@ -206,10 +207,12 @@ If you need help at any point when contributing, the [New Contributor Ambassador | [Italian](./content/it/README.md) | [Vietnamese](./content/vi/README.md) | | [Japanese](./content/ja/README.md) | | +--- ## Code of conduct Participation in the Kubernetes community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). -## Thank you +--- +## Thank you! -Kubernetes thrives on community participation, and we appreciate your contributions to our website and our documentation! +Thank you for contributing to Kubernetes! Your support and participation make a difference. From 1af78a2d5cb9b3e20236a2dedcc69728ea274e92 Mon Sep 17 00:00:00 2001 From: Priyanka Behera Date: Wed, 13 Nov 2024 18:21:40 +0530 Subject: [PATCH 2/2] made changes --- README.md | 176 +++++++++++++++++++++++++++--------------------------- 1 file changed, 87 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 9179fdce155ac..cda747c1f3fb3 100644 --- a/README.md +++ b/README.md @@ -1,158 +1,157 @@ # The Kubernetes documentation -[![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-main-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest) +[![Netlify Status](https://api.netlify.com/api/v1/badges/be93b718-a6df-402a-b4a4-855ba186c97d/deploy-status)](https://app.netlify.com/sites/kubernetes-io-main-staging/deploys) [![GitHub release](https://img.shields.io/github/release/kubernetes/website.svg)](https://github.com/kubernetes/website/releases/latest) Welcome! This repository contains the assets required to build the [Kubernetes website and documentation](https://kubernetes.io/). We're glad you're interested in contributing. ## Table of Contents -1. [Using This Repository](#using-this-repository) -2. [Prerequisites](#prerequisites) -3. [Running the Website](#running-the-website) -4. [Building the API Reference Pages](#building-the-api-reference-pages) -5. [Troubleshooting](#troubleshooting) -6. [Get Involved with SIG Docs](#get-involved-with-sig-docs) -7. [Contributing to the Docs](#contributing-to-the-docs) -8. [Localization READMEs](#localization-readmes) -9. [Code of Conduct](#code-of-conduct) -10.[Thank You!](#thank-you) + - [Using This Repository](#using-this-repository) + - [Prerequisites](#prerequisites) + - [Running the Website](#running-the-website) + - [Building the API Reference Pages](#building-the-api-reference-pages) + - [Troubleshooting](#troubleshooting) + - [Get Involved with SIG Docs](#get-involved-with-sig-docs) + - [Contributing to the Docs](#contributing-to-the-docs) + - [Localization READMEs](#localization-readmes) + - [Code of Conduct](#code-of-conduct) + - [Thank You!](#thank-you) + ---- ## Using this repository -Run the website locally using [Hugo (Extended version)](https://gohugo.io/), or in a container runtime (recommend for deployment consistency with the live site). +You can run the website locally using [Hugo (Extended version)](https://gohugo.io/), or in a container runtime (recommended for deployment consistency with the live site). ## Prerequisites -To use this repository, you'll need: +To use this repository, you will need: - [npm](https://www.npmjs.com/) - [Go](https://go.dev/) - [Hugo (Extended version)](https://gohugo.io/) - A container runtime, like [Docker](https://www.docker.com/). -> [!NOTE] -Ensure you install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L11). +> [!NOTE] + Ensure you install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L11). ## Running the Website -**Initial Setup** +### Initial Setup - 1. **Clone the Repository**: +1. **Clone the Repository**: - ```bash - git clone https://github.com/kubernetes/website.git - cd website - ``` +```bash +git clone https://github.com/kubernetes/website.git +cd website +``` - >[!Note] - The Kubernetes website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme).So, pulling in submodule is strongly recommended. +>[!Note] +The Kubernetes website uses the [Docsy Hugo theme](https://github.com/google/docsy#readme).So, pulling in submodule is strongly recommended. - 2. **Initialize Submodules and Dependencies**: +2. **Initialize Submodules and Dependencies**: - - **Windows**: +- **Windows**: - ```bash - git submodule update --init --recursive --depth 1 - ``` +```bash +git submodule update --init --recursive --depth 1 +``` - - **Linux / Unix**: +- **Linux / Unix**: - ```bash - make module-init - ``` +```bash +make module-init +``` -**Running using a container** +### Running using a container - 1. **Build the site**: +1. **Build the site**: - ```bash - # You can set $CONTAINER_ENGINE to the name of any Docker-like container tool - make container-serve - ``` - 2. Open in a browser to view the website. +```bash +# You can set $CONTAINER_ENGINE to the name of any Docker-like container tool +make container-serve +``` +2. Open in a browser to view the website. - >[!Note] - If you see errors, increase the amount of allowed CPU and memory usage for Docker on your machine ([MacOS](https://docs.docker.com/desktop/settings/mac/) and [Windows](https://docs.docker.com/desktop/settings/windows/)). +>[!Note] +If you see errors, increase the amount of allowed CPU and memory usage for Docker on your machine ([MacOS](https://docs.docker.com/desktop/settings/mac/) and [Windows](https://docs.docker.com/desktop/settings/windows/)). -**Running Locally using Hugo** +### Running Locally using Hugo - To install dependencies, deploy and test the site: +To install dependencies, deploy and test the site: - - **macOS/Linux**: +- **macOS/Linux**: - ```bash - npm ci - make serve - ``` +```bash +npm ci +make serve +``` - - **Windows (PowerShell)**: +- **Windows (PowerShell)**: - ```powershell - npm ci - hugo.exe server --buildFuture --environment development - ``` +```powershell +npm ci +hugo.exe server --buildFuture --environment development +``` - Vist to see your changes. ---- +Visit to see your changes. -### Updating API Reference Pages +## Updating API Reference Pages The API reference pages are built from the Swagger (OpenAPI) specification using [gen-resourcesdocs](https://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs). -**Steps to Update for a New Kubernetes Release**: +### Steps to Update for a New Kubernetes Release: 1. **Pull in the api-ref-generator submodule**: - ```bash - git submodule update --init --recursive --depth 1 - ``` +```bash +git submodule update --init --recursive --depth 1 +``` 2. **Update the Swagger specification**: - ```bash - curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json - ``` +```bash +curl 'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json' > api-ref-assets/api/swagger.json +``` 3. **Update the configuration files** (`toc.yaml` and `fields.yaml`) in `api-ref-assets/config/` to reflect the new release. 4. **Build the pages**: - ```bash - make api-reference - ``` +```bash +make api-reference +``` 5. **Test locally by serving the site**: - ```bash - make container-serve - ``` +```bash +make container-serve +``` - View at: +View at: 6. Once everything is updated, create a Pull Request with the new API reference pages. ---- + ## Troubleshooting -1. **TOCSS Error** - -This issue occurs if the Hugo Extended version isn’t installed. Verify it shows `extended` by running: +### TOCSS Error +-This issue occurs if the Hugo Extended version isn’t installed. Verify it shows `extended` by running: - ```bash - hugo version - ``` +```bash +hugo version +``` - -In the [release page](https://github.com/gohugoio/hugo/releases) look for archives with `extended` in the name. +-In the [release page](https://github.com/gohugoio/hugo/releases) look for archives with `extended` in the name. -2. **Too Many Open Files(macOS)** - -Check the open file limit: - ```bash - launchctl limit maxfiles - ``` +### Too Many Open Files(macOS) +-Check the open file limit: +```bash +launchctl limit maxfiles +``` + +-Follow the [gist instructions](https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c) to increase the limit. - -Follow the [gist instructions](https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c) to increase the limit. ---- ## Get involved with SIG Docs @@ -164,7 +163,6 @@ You can also reach the maintainers of this project at: - [Get an invite for this Slack](https://slack.k8s.io/) - [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) ---- ## Contributing to the Docs Click the **Fork** button to create a copy of this repository in your GitHub account. Make any changes in your fork and, when ready, create a pull request. @@ -182,7 +180,6 @@ For more information about contributing to the Kubernetes documentation, see: - [Localizing Kubernetes Documentation](https://kubernetes.io/docs/contribute/localization/) - [Introduction to Kubernetes Docs](https://www.youtube.com/watch?v=pprMgmNzDcw) ---- **New contributor ambassadors** @@ -207,12 +204,13 @@ If you need help while contributing, the [New Contributor Ambassadors](https://k | [Italian](./content/it/README.md) | [Vietnamese](./content/vi/README.md) | | [Japanese](./content/ja/README.md) | | ---- + + ## Code of conduct Participation in the Kubernetes community is governed by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). ---- + ## Thank you! Thank you for contributing to Kubernetes! Your support and participation make a difference.