GitHub pages update Mon Nov 20 18:12:44 EST 2023

Signed-off-by: Fanit Kolchina <[email protected]>

API_STYLE_GUIDE.md

@@ -0,0 +1,197 @@
+# API Style Guide
+
+This guide provides the basic structure for creating OpenSearch API documentation. It includes the various elements that we feel are most important to creating complete and useful API documentation, as well as description and examples where appropriate.
+
+Depending on the intended purpose of the API, *some sections will be required while others may not be applicable*.
+
+Use the [API_TEMPLATE](templates/API_TEMPLATE.md) to create an API documentation page.
+
+### A note on terminology ###
+
+Terminology for API parameters varies in the software industry, where two or even three names may be used to label the same type of parameter. For consistency, we use the following nomenclature for parameters in our API documentation:
+* *Path parameter* – "path parameter" and "URL parameter" are sometimes used synonymously. To avoid confusion, we use "path parameter" in this documentation.
+* *Query parameter* – This parameter name is often used synonymously with "request parameter." We use "query parameter" to be consistent.
+
+### General usage for code elements
+
+When you describe any code element in a sentence, such as an API, a parameter, or a field, you can use the noun name. 
+  *Example usage*:
+  The time field provides a timestamp for job completion.
+
+When you provide an exact example with a value, you can use the code element in code font. 
+  *Example usage*: 
+  The response provides a value for `time_field`, such as “timestamp.” 
+
+Provide a REST API call example in `json` format. Optionally, also include the `curl` command if the call can only be executed in a command line.
+
+## Basic elements for documentation
+
+The following sections describe the basic API documentation structure. Each section is discussed under its respective heading. Include only those elements appropriate to the API. 
+
+Depending on where the documentation appears within a section or subsection, heading levels may be adjusted to fit with other content.
+
+1. Name of API (heading level 2)
+1. (Optional) Path and HTTP methods (heading level 3)
+1. Path parameters (heading level 3)
+1. Query parameters (heading level 3)
+1. Request fields (heading level 3)
+1. Example request (heading level 4)
+1. Example response (heading level 4)
+1. Response fields (heading level 3)
+
+## API name
+
+Provide an API name that describes its function, followed by a description of its top use case and any usage recommendations.
+
+*Example function*: "Autocomplete queries"
+
+Use sentence capitalization for the heading (for example, "Create or update mappings"). When you refer to the API operation, you can use lowercase with code font.
+
+If there is a corresponding OpenSearch Dashboards feature, provide a “See also” link that references it. 
+*Example*: “To learn more about monitor findings, see [Document findings](https://opensearch.org/docs/latest/monitoring-plugins/alerting/monitors/#document-findings)."
+
+If applicable, provide any caveats to its usage with a note or tip, as in the following example:
+
+"If you use the Security plugin, make sure you have the appropriate permissions."
+(To set this point in note-style format, follow the text on the next line with {: .note})
+
+### Path and HTTP methods
+
+For relatively complex API calls that include path parameters, it's sometimes a good idea to provide an example so that users can visualize how the request is properly formed. This section is optional and includes examples that illustrate how the endpoint and path parameters fit together in the request. The following is an example of this section for the nodes stats API:
+
+```json
+GET /_nodes/stats
+GET /_nodes/<node_id>/stats
+GET /_nodes/stats/<metric>
+GET /_nodes/<node_id>/stats/<metric>
+GET /_nodes/stats/<metric>/<index_metric>
+GET /_nodes/<node_id>/stats/<metric>/<index_metric>
+```
+
+### Path parameters
+
+While the API endpoint states a point of entry to a resource, the path parameter acts on the resource that precedes it. Path parameters come after the resource name in the URL.
+
+In the following example, the resource is `scroll` and its path parameter is `<scroll_id>`:
+
+```json
+GET _search/scroll/<scroll_id>
+```
+
+Introduce what the path parameters can do at a high level. Provide a table with parameter names and descriptions. Include a table with the following columns:
+*Parameter* – Parameter name in plain font.
+*Data type* – Data type capitalized (such as Boolean, String, or Integer).
+*Description* – Sentence to describe the parameter function, default values or range of values, and any usage examples.
+
+Parameter | Data type | Description
+:--- | :--- | :---
+
+### Query parameters
+
+In terms of placement, query parameters are always appended to the end of the URL and located to the right of the operator "?". Query parameters serve the purpose of modifying information to be retrieved from the resource.
+
+In the following example, the endpoint is `aliases` and its query parameter is `v` (provides verbose output):
+
+```json
+GET _cat/aliases?v
+```
+
+Include a paragraph that describes how to use the query parameters with an example in code font. Include the query parameter operator "?" to delineate query parameters from path parameters.
+
+For GET and DELETE APIs: Introduce what you can do with the optional parameters. Include a table with the same columns as the path parameter table.
+
+Parameter | Data type | Description
+:--- | :--- | :---
+
+### Request fields
+
+For PUT and POST APIs: Introduce what the request fields are allowed to provide in the body of the request.
+
+Include a table with these columns: 
+*Field* – Field name in plain font.
+*Data type* – Data type capitalized (such as Boolean, String, or Integer).
+*Description* – Sentence to describe the field’s function, default values or range of values, and any usage examples.
+
+Field | Data type | Description
+:--- | :--- | :--- 
+
+#### Example request
+
+Provide a sentence that describes what is shown in the example, followed by a cut-and-paste-ready API request in JSON format. Make sure that you test the request yourself in the Dashboards Dev Tools console to make sure it works. See the following examples.
+
+The following request gets all the settings in your index:
+
+```json
+GET /sample-index1/_settings
+```
+
+The following request copies all of your field mappings and settings from a source index to a destination index:
+
+```json
+POST _reindex
+{
+   "source":{
+      "index":"sample-index-1"
+   },
+   "dest":{
+      "index":"sample-index-2"
+   }
+}
+```
+
+#### Example response
+
+Include a JSON example response to show what the API returns. See the following examples.
+
+The `GET /sample-index1/_settings` request returns the following response fields: 
+
+```json
+{
+  "sample-index1": {
+    "settings": {
+      "index": {
+        "creation_date": "1622672553417",
+        "number_of_shards": "1",
+        "number_of_replicas": "1",
+        "uuid": "GMEA0_TkSaamrnJSzNLzwg",
+        "version": {
+          "created": "135217827",
+          "upgraded": "135238227"
+        },
+        "provided_name": "sample-index1"
+      }
+    }
+  }
+}
+```
+
+The `POST _reindex` request returns the following response fields: 
+
+```json
+{
+  "took" : 4,
+  "timed_out" : false,
+  "total" : 0,
+  "updated" : 0,
+  "created" : 0,
+  "deleted" : 0,
+  "batches" : 0,
+  "version_conflicts" : 0,
+  "noops" : 0,
+  "retries" : {
+    "bulk" : 0,
+    "search" : 0
+  },
+  "throttled_millis" : 0,
+  "requests_per_second" : -1.0,
+  "throttled_until_millis" : 0,
+  "failures" : [ ]
+}
+```
+
+### Response fields
+
+For PUT and POST APIs: Define all allowable response fields that can be returned in the body of the response.
+
+Field | Data type | Description
+:--- | :--- | :---

CNAME

@@ -0,0 +1 @@
+docs-beta.opensearch.org

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+## Code of Conduct
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
+For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
+[email protected] with any additional questions or comments.

CONTRIBUTING.md

@@ -0,0 +1,144 @@
+- [Creating an issue](#creating-an-issue)
+- [Contributing content](#contributing-content)
+   - [Contribution workflow](#contribution-workflow)
+   - [Before you start](#before-you-start)
+   - [Making minor changes](#making-minor-changes)
+   - [Making major changes](#making-major-changes)
+      - [Setting up your local copy of the repository](#setting-up-your-local-copy-of-the-repository)
+      - [Making, viewing, and submitting changes](#making-viewing-and-submitting-changes)
+- [Review process](#review-process)
+   - [Style linting](#style-linting)
+- [Getting help](#getting-help)
+
+# Contributing guidelines
+
+Thank you for your interest in improving the OpenSearch documentation! We value and appreciate all feedback and contributions from our community, including requests for additional documentation, corrections to existing content, and reports of technical issues with the documentation site. 
+
+You can [create an issue](#creating-an-issue) asking us to change the documentation or [contribute content](#contributing-content) yourself.
+
+NOTE: If you’d like to contribute but don't know where to start, try browsing existing [issues](https://github.com/opensearch-project/documentation-website/issues). Our projects use custom GitHub issue labels for status, version, type of request, and so on. We recommend starting with any issue labeled "good first issue" if you're a beginner or "help wanted" if you're a more experienced user. 
+
+## Creating an issue
+
+Use the documentation issue template to describe the change you'd like to make:
+
+1. Go to https://github.com/opensearch-project/documentation-website/issues and select **New issue**.
+1. Enter the requested information, including as much detail as possible, especially which version or versions the request affects.
+1. Select **Submit new issue**. 
+
+The `untriaged` label is assigned automatically. During the triage process, the Documentation team will add the appropriate labels, assign the issue to a technical writer, and prioritize the request. We may follow up with you for additional information. 
+
+## Contributing content
+
+There are two ways to contribute content, depending on the magnitude of the change:
+
+- [Minor changes](#making-minor-changes): For small changes to existing files, like fixing typos or adding parameters, you can edit files in GitHub directly. This approach does not require cloning the repository and does not allow you to test the documentation.
+- [Major changes](#making-major-changes): For changes you want to test first, like adding new or reorganizing pages or adding a table or section, you can edit files locally and push the changes to GitHub. This approach requires setting up a local version of the repository and allows you to test the documentation.
+
+### Contribution workflow
+
+The workflow for contributing documentation is the same as the one for contributing code:
+
+- Make your changes.
+- Build the documentation website to check your work (only possible if you are making changes locally).
+- Submit a [pull request](https://github.com/opensearch-project/documentation-website/pulls) (PR).
+- A maintainer reviews and merges your PR.
+
+### Before you start
+
+Before contributing content, make sure to read the following resources:
+- [README](README.md)
+- [OpenSearch Project Style Guidelines](STYLE_GUIDE.md)
+- [API Style Guide](API_STYLE_GUIDE.md)
+- [Formatting Guide](FORMATTING_GUIDE.md) 
+
+NOTE: Make sure that any documentation you submit is your own work or work that you have the right to submit. We respect the intellectual property rights of others, and as part of contributing, we'll ask you to sign your contribution with a [Developer Certificate of Origin (DCO)](https://github.com/opensearch-project/.github/blob/main/CONTRIBUTING.md#developer-certificate-of-origin) stating that you have the right to submit your contribution and that you understand that we will use your contribution. 
+
+### Making minor changes
+
+If you want to make minor changes to an existing file, you can use this approach:
+
+1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+
+1. In your fork on GitHub, navigate to the file that you want to change.
+
+1. In the upper-right corner, select the pencil icon and edit the file.
+
+1. In the upper-right corner, select **Commit changes...***. Enter the commit message and optional description and select **Create a new branch for this commit and start a pull request**.
+
+### Making major changes
+
+If you're adding a new page or making major changes to the documentation, such as adding new images, sections, or styling, we recommend that you work in a local copy of the repository and test the rendered HTML before submitting a PR. 
+
+#### Setting up your local copy of the repository
+
+Follow these steps to set up your local copy of the repository:
+
+1. [Fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork.
+
+1. Navigate to your cloned repository.
+
+1. Install [Ruby](https://www.ruby-lang.org/en/) if you don't already have it. We recommend [RVM](https://rvm.io/), but you can use any method you prefer:
+
+   ```
+   curl -sSL https://get.rvm.io | bash -s stable
+   rvm install 2.7
+   ruby -v
+   ```
+
+1. Install [Jekyll](https://jekyllrb.com/) if you don't already have it:
+
+   ```
+   gem install bundler jekyll
+   ```
+
+1. Install the Jekyll dependencies:
+
+   ```
+   bundle install
+   ```
+
+#### Making, viewing, and submitting changes 
+
+Here's how to build the website, make changes, and view them locally:
+
+1. Build the website:
+
+   ```
+   sh build.sh    
+   ```
+
+   The build script should automatically open your web browser, but if it doesn't, open [http://localhost:4000/docs/](http://localhost:4000/docs/).
+
+1. Create a new branch against the latest source on the main branch. 
+
+1. Edit the Markdown files that you want to change.
+
+1. When you save a file, Jekyll automatically rebuilds the site and refreshes your web browser. This process can take 60--90 seconds.
+
+1. When you're happy with how everything looks, commit, [sign off](https://github.com/src-d/guide/blob/9171d013c648236c39faabcad8598be3c0cf8f56/developer-community/fix-DCO.md#how-to-prevent-missing-sign-offs-in-the-future), push your changes to your fork, and submit a PR.
+
+    Note that a PR requires DCO sign-off before we can merge it. You can use the -s command line option to append this automatically to your commit message, for example, `git commit -s -m 'This is my commit message'`. For more information, see https://github.com/apps/dco.
+
+## Review process
+
+We greatly appreciate all contributions to the documentation and will review them as quickly as possible. 
+
+During the PR process, expect that there will be some back-and-forth. If you want your contribution to be merged quickly, try to respond to comments in a timely fashion, and let us know if you don't want to continue with the PR. 
+
+We use the [Vale](https://github.com/errata-ai/vale) linter to ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md). Addressing Vale comments on the PR expedites the review process. You can also install Vale locally so you can address the comments before creating a PR. For more information, see [Style linting](#style-linting).
+
+If we accept the PR, we will merge it and will backport it to the appropriate branches.
+
+### Style linting
+
+To ensure that our documentation adheres to the [OpenSearch Project Style Guidelines](STYLE_GUIDE.md), we use the [Vale](https://github.com/errata-ai/vale) linter. Addressing Vale comments on the PR expedites the review process. You can also install Vale locally as follows so you can address the comments before creating a PR:
+
+1. Run `brew install vale`.
+2. Run `vale *` from the documentation site root directory to lint all Markdown files. To lint a specific file, run `vale /path/to/file`.
+
+Optionally, you can install the [Vale VSCode](https://github.com/chrischinchilla/vale-vscode) extension, which integrates Vale with Visual Studio Code. By default, only _errors_ and _warnings_ are underlined. To change the minimum alert level to include _suggestions_, go to **Vale VSCode** > **Extension Settings** and select **suggestion** in the **Vale > Vale CLI: Min Alert Level** dropdown list. 
+
+## Getting help
+
+For help with the contribution process, reach out to one of the [points of contact](README.md#points-of-contact).