Merge branch 'main' into add-search

Signed-off-by: Gergely Csatari <[email protected]>

README.md

@@ -121,6 +121,7 @@ it is manageable via Nephio.
 Please use the documentation links below to learn more about Nephio, or check out our [Learning Nephio](https://wiki.nephio.org/display/HOME/Learning+with+Nephio+R1) series. The video series includes a [demo video](https://youtu.be/mFl71sy2Pdc) and short articles about different aspects of Nephio.
 
 ## User Documentation
+
 * [Release Notes for each Nephio release](https://docs.nephio.org/docs/release-notes/)
 * [Demo Sandbox Environment Installation](https://docs.nephio.org/docs/guides/install-guides/)
 * [User Guide](https://docs.nephio.org/docs/guides/user-guides/)
@@ -129,4 +130,4 @@ Please use the documentation links below to learn more about Nephio, or check ou
 
 * [Developer Documentation](https://github.com/nephio-project/nephio)
 * [Developer Guide](https://docs.nephio.org/docs/guides/contributor-guides/)
-* [Project Resources](https://github.com/nephio-project/docs/blob/main/resources.md)
+* [Project Resources](https://github.com/nephio-project/docs/blob/main/resources.md)

content/en/docs/_index.md

@@ -5,89 +5,91 @@ menu: {main: {weight: 20}}
 weight: 1
 ---
 
-Our mission is "to deliver carrier-grade, simple, open, Kubernetes-based cloud
-native intent automation and common automation templates that materially
-simplify the deployment and management of multi-vendor cloud infrastructure and
-network functions across large scale edge deployments." But what does that mean?
+Our mission is "to deliver carrier-grade, simple, open, Kubernetes-based
+cloud-native intent automation and common automation templates that materially
+simplify the deployment and management of multivendor cloud infrastructure and
+network functions across large-scale edge deployments." But what does that mean?
 With this release and the accompanying documentation, we hope to make that
 clear.
 
-The mission outlines the basic goals and the [About Nephio
+Our mission outlines the basic goals. The [About Nephio
 page](https://nephio.org/about/) describes the high-level architecture of
 Nephio. It is important to understand that Nephio is about managing complex,
-inter-related workloads *at scale*. If we simply want to deploy a network
-function, existing methods like Helm charts and scripts are sufficient.
-Similarly, if we want to deploy some infrastructure, then using existing
-Infrastructure-as-Code tools can accomplish that. Configuring running network
-functions can already be done today with element managers.
+interrelated workloads *at scale*. If we simply want to deploy a network
+function, then existing methods, such as Helm charts and scripts, are
+sufficient. Similarly, if we want to deploy some infrastructure, then using
+existing Infrastructure-as-Code tools can accomplish that. Configuring running
+network functions can already be done today with element managers.
 
-So, why do we need Nephio? The problems Nephio wants to solve start only
-once we try to operate at scale. "Scale" here does not simply mean "large number
-of sites". It can be across many different dimensions: number of sites, number
-of services, number of workloads, size of the individual workloads, number of
-machines needed to operate the workloads, complexity of the organization running
-the workloads, and other factors. The fact that our infrastructure, workloads,
-and workload configurations are all interconnected dramatically increases
-the difficulty in managing these architectures at scale.
+Why do we need Nephio? The problems Nephio aims to solve start only
+once we try to operate at scale. "Scale", in this case, does not simply mean
+"a large number of sites". "Scale" can encompass many different areas: the
+number of sites, services, and workloads, the size of each individual workload,
+the number of machines needed to operate the workloads, the complexity of the
+organization running the workloads, and other factors. The fact that our
+infrastructure, workloads, and workload configurations are all interconnected
+greatly increases the difficulty in managing these architectures at scale.
 
 To address these challenges, Nephio follows a [few basic
 principles](https://cloud.google.com/blog/topics/telecommunications/network-automation-csps-linus-nephio-cloud-native)
-that experience has shown to enable higher scaling with less management overhead:
-- *Intent-driven* to enable the user to specify "what they want" and let the
-  system figure out "how to make that happen".
-- *Distributed actuation* to increase reliability across widely distributed
-  fleets.
-- *Uniformity in systems* to reduce redundant tooling and processes, and
-  simplify operations.
+that experience has shown to enable higher scaling with fewer management
+overheads. These principles are as follows:
+- It is *Intent-driven* to enable the user to specify what they want and
+  let the system figure out how to make that happen.
+- It has *Distributed actuation* to increase reliability across widely
+  distributed fleets.
+- It has *Uniformity in systems* to reduce redundant tooling and processes,
+  and simplify operations.
 
-Additionally, Nephio leverages the "configuration as data" principle. This
+Nephio also leverages the "configuration as data" principle. This
 methodology means that the "intent" is captured in a machine-manageable format
 that we can treat as data, rather than code. In Nephio, we use the Kubernetes
-Resource Model (KRM) to capture intent. As Kubernetes itself is already an
+Resource Model (KRM) to capture the intent. As Kubernetes itself is already an
 intent-driven system, this model is well suited to our needs.
 
-To understand why we need to treat configuration as data, let's consider an
-example. In a given instance, a network function may have, say, 100 parameters
-that need to be decided upon. When we have 100 such network functions, across
-10,000 clusters, this results in 100,000,000 inputs we need to define and
-manage. Handling that sheer number of values, with their interdependencies and a need
-for consistency management between them, requires *data management* techniques,
-not *code* management techniques. This is why existing methodologies begin to
-break down at scale, particular edge-level scale.
+To understand why we need to treat configuration as data, let us consider an
+example. In a given instance, a network function may have, for example, 100
+parameters that need to be decided upon. 100 such network functions, across
+10,000 clusters, results in 100,000,000 inputs that need to be defined and
+managed. Handling such a large number of values, with their interdependencies
+and a need for consistency management between them, requires *data management*
+techniques, rather than *code* management techniques. This is why existing
+methodologies begin to break down at scale, particular at the edge-level scale.
 
-Consider as well that no single human will understand all of those values. Those
-values relate not only to workloads, but also to the infrastructure we need to
-support those workloads. They require different areas of expertise and different
-organizational boundaries of control. For example, you will need input from
-network planning (IP address, VLAN tags, ASNs, etc.), input from
-compute infrastructure teams (types of hardware or VMs available, OS available),
-Kubernetes platform teams, security teams, network function experts, and many,
-many other individuals and teams. Each of those teams will have their own
-systems for tracking the values they control, and processes for allocating and
-distributing those values. This coordination between teams is a fundamental
-*organizational* problem with operating at scale. The existing tools and methods
-do not even attempt to address these parts of the problem; they *start* once all
-of the "input" decisions are made.
+It should also be considered that no individual human will be able to understand
+all of these values. These values relate not only to the workloads, but also to
+the infrastructure that is required to support the workloads. They require
+different areas of expertise and different organizational boundaries of control.
+For example, you will need input from network planning (IP address, VLAN tags,
+ASNs, and so on), input from the compute infrastructure teams (types of hardware,
+or available VMs or OSs), the Kubernetes platform teams, the security teams, the
+network function experts, and many other individuals and teams. Each of these
+teams will have their own systems for tracking the values they control, as well
+as processes for allocating and distributing those values. This coordination
+between teams is a fundamental *organizational* problem with operating at scale.
+The existing tools and methods do not even attempt to address these parts of the
+problem. They *start* once all of the "input" decisions are made.
 
-The Nephio project believes the organizational challenge around figuring out
-these values is actually one of the primary limiting factors to achieving
-efficient management of large, complex systems at scale. This gets even harder
-when we realize that we need to manage changes to these values over time, and
-understand how changes to some values implies the need to change other values.
-This challenge is currently left to ad hoc processes that differ across
+The Nephio project believes that the organizational challenge of figuring out
+these values is one of the primary limiting factors to achieving the efficient
+management of large, complex systems at scale. This challenge becomes even
+greater when we understand the need to manage the changes to these values over
+time, and how changes to some values implies the need to change other values.
+This challenge is currently left to ad-hoc processes that differ across
 organizations. Nephio is working on how to structure the intent to make it
 manageable using data management techniques.
 
-This release of Nephio focuses:
-- Demonstrating the core Nephio principles such as Configuration-as-Data and
+This Nephio release focuses on the following:
+- Demonstrating the core Nephio principles, such as Configuration-as-Data and
   leveraging the intent-driven, active-reconciliation nature of Kubernetes.
 - Infrastructure orchestration/automation using controllers based on
-  the Cluster API. At this time only KIND cluster creation is supported.
-- Orchestration/automation of 5G Core and RAN network functions deployment and
-  management. 
+  the Cluster API. Currently, only Kubernetes in Docker (KIND) cluster creation
+  is supported.
+- Orchestration/automation of the deployment and management of 5G Core and RAN
+  networks. 
 
-While the current releases uses Cluster API, KIND, and free5gc/OAI for demonstration
-purposes, the exact same principles and even code can be used for managing other
-infrastructure and network functions. The *uniformity in systems* principle
-means that as long as something is manageable via the Kubernetes Resource Model,
-it is manageable via Nephio.
+While the current release uses Cluster API, KIND, and free5gc/OAI for
+demonstration purposes, the same principles and code can be used for managing
+other infrastructure and network functions. The *uniformity in systems*
+principle means that as long as something is manageable via the Kubernetes
+Resource Model, it is manageable via Nephio.

content/en/docs/guides/contributor-guides/documentation.md

@@ -0,0 +1,88 @@
+---
+title: Documentation
+description: >
+  Contributors guide for the Nephio documentation
+weight: 5
+---
+
+## Framework
+
+The Nephio documentation is built with the .md / Hugo / Docsy / Netlify framework.
+
+* **.md:** The documentation itself is written in Markdown (,md) with some Hugo and Docsy related extensions. The .md
+  files are stored and managed in a Git repo in [nephio-project/docs](https://github.com/nephio-project/docs).
+* **Hugo:** [Hugo](https://gohugo.io/) is used to render the documentation fo static html pages.
+* **Docsy:** [Docsy](https://www.docsy.dev/) is a theme for Hugo what we use to provide the basic structure and look
+  and feel of the documentation.
+* **Netlify:** [Netlify](https://www.netlify.com/) is a service to host documentation. We are hosting the Nephio    
+  documentation from here.
+
+## Creating issues
+
+Documentation issues are handled in the nephio-project/nephio repository's [issue handler](https://github.com/nephio-project/nephio/issues).
+Add the *area/docs* and the *documentation* labels to the issues created for the documentation.
+
+## Style guide
+
+* Use US English in the documentation
+* Do not add manually a table of contents to the documents. Hugo and Docsy takes care of this.
+* Do not use H1 (#) headers in the documents. Docsy generates a H1 header to every document consistent with the title
+  of the document. Start the headings with H2 (##)
+* Use the built in alerts for notes and alerts
+
+  ```go-html-template
+  {{%/* alert title="Warning" color="primary" */%}}
+  This is a note.
+  {{%/* /alert */%}}
+  ```
+
+  ```go-html-template
+  {{%/* alert title="Warning" color="warning" */%}}
+  This is a warning.
+  {{%/* /alert */%}}
+  ```
+* Colors to be used when creating figures are [here](https://color.adobe.com/Nephio-secondary-colors-color-theme-0bbcdea2-0533-4ab3-812f-f752f30b5b40/)
+* If you add any commands to the content inline surround the comand with backticks (\` \`), like \`ls -la\`
+* Do not surround IP addresses, domain names or any other identifyers with backticks. Use italics (\* \*) to mark any
+  inline IP address, domain name, file name, file location or similar.
+* Whenever possible define the type of code for your code blocks
+  * \```bash for all shell blocks
+  * \```golang for all Go blocks
+  * \```yaml for all YAML blocks
+  * \``` yang for all YANG blocks
+  * a full list of language identifyers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages)
+* Do not add any TBDs to the documentation. If something is missing create an [issue](https://github.com/nephio-project/nephio/issues) for it
+
+## How to contribute
+
+Follow the Nephio contribution process, based on GitHub pull requests and Prow. Contributions to the Nephio
+documentation require the [Nephio CLA](https://contributor.easycla.lfx.linuxfoundation.org/#/cla/project/084c4c00-cece-4fe0-b259-7132f445025e/user/2e82f427-4b62-48c8-a43f-d46dc74cc74b).
+
+### Build your environment
+
+Following the description [here](https://github.com/nephio-project/docs?tab=readme-ov-file#setting-up-the-environment).
+
+### Tests before submitting a pull request
+
+* Build and deploy the documentation locally
+  * run `hugo serve`
+* Build in a same way as Netlify is doing it
+  * run `hugo --gc --minify`
+* Check links
+  * Install and run [linkspector](https://github.com/UmbrellaDocs/linkspector)
+    ```bash
+    npm install -g @umbrelladocs/linkspector
+    linkinspector check -c .linkspector.yml
+    ```
+
+### Checks before submitting a pr
+
+## FAQ
+
+1. How do I check the documentation links on the documentation before I check in my changes?
+
+    Install and run *linkspector*
+    ```
+    npm install -g @umbrelladocs/linkspector
+    linkinspector check -c .linkspector.yml
+    ```

content/en/docs/porch/contribturos-guide/environment-setup.md

@@ -15,28 +15,22 @@ through the [Starting with Porch tutorial](../using-porch/install-and-using-porc
 As your Dev environment, you can run the code on a remote VM and use the
 [VSCode Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
 plugin to connect to it.
-TODO: re-check WSL2 + Docker Desktop setup
 
 {{% /alert %}}
 
 ## Extra steps for MacOS users
 
 The script the `make deployment-config` target to generate the deployment files for porch. The scripts called by this
-make target use recent `bash` additions and expect the gnu version of the `sed` command. MacOS comes with `bash` 3.x.x
-by default and with a version of `sed` that is incompatible with gnu `sed`. TODO: check if sed is indeed still used.
+make target use recent `bash` additions. MacOS comes with `bash` 3.x.x
 
 1. Install `bash` 4.x.x or better of `bash` using homebrew, see
    [this this post for details](https://apple.stackexchange.com/questions/193411/update-bash-to-version-4-0-on-osx)
-2. Install `gsed` using homebrew, see
-   [this post for details](https://stackoverflow.com/questions/4247068/sed-command-with-i-option-failing-on-mac-but-works-on-linux)
-3. `sudo ln -s /opt/homebrew/bin/gsed /opt/homebrew/bin/sed` create a soft link for `sed` from `gsed`
-4. Ensure that `/opt/homebrew/bin` is earlier in your path than `/bin` and `/usr/bin`
+2. Ensure that `/opt/homebrew/bin` is earlier in your path than `/bin` and `/usr/bin`
 
 {{% alert title="Note" color="primary" %}}
 
-The changes above **permanently** change the `bash` version and `sed` for **all** applications and may cause side
-effects. You may wish to revert the changes (particularly the `sed-->gsed` soft link) when you complete your work on
-Porch.
+The changes above **permanently** change the `bash` version for **all** applications and may cause side
+effects. 
 
 {{% /alert %}}