From 9c53f5d6585670ee5a5cbdc2a2feeb325f8133cd Mon Sep 17 00:00:00 2001 From: Karl Cardenas Date: Tue, 19 Sep 2023 11:57:11 -0700 Subject: [PATCH 1/4] docs: updated README and release concurrency --- .github/workflows/release.yaml | 2 +- README.md | 120 ++++++++++++++++++++++++--------- 2 files changed, 89 insertions(+), 33 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 8195b04300..f80854931b 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -21,7 +21,7 @@ env: concurrency: - group: production-${{ github.ref }} + group: production-${{ github.workflow }} cancel-in-progress: true jobs: diff --git a/README.md b/README.md index 9ce9436f49..5107758302 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,13 @@ There are two local development paths available; Docker based, and non-Docker ba To contribute, we recommend having the following software installed locally on your workstation. -- Text Editor +- VScode or a text editor + - [Docker](https://docs.docker.com/desktop/) + - git configured and access to github repository -- node and npm (optional) + +- Node.js and npm (optional) ## Local Development (Docker) @@ -36,16 +39,24 @@ To start the Dockererized local development server, issue the command: make docker-start ``` -The local development server is ready when the following output is displayed in your terminal. +The local development server is ready when the following output is displayed in your terminal. ```shell -You can now view root in the browser. -⠀ - Local: http://localhost:9000/ - On Your Network: http://172.17.0.2:9000/ -⠀ +npm run start + +> spectro-cloud-docs@4.0.0 start +> docusaurus start --host 0.0.0.0 --port 9000 + +[INFO] Starting the development server... +[SUCCESS] Docusaurus website is running at: http://localhost:9000/ -Visit [http://localhost:9000](http://localhost:9000) to view the local development documentation site. +✔ Client + Compiled successfully in 8.39s + +client (webpack 5.88.2) compiled successfully +``` + +Open up a browser and navigate to [http://localhost:9000](http://localhost:9000) to view the documentation website. To exit from the local development Docker container. Press `Ctrl + Z`. @@ -66,32 +77,31 @@ cd librarium make init ``` -# Documentation Content +## Documentation Content -Create a branch if needed. This will keep your work separated from the rest of your changes. +Create a branch to keep track of all your changes. ```sh git checkout -b ``` -To preview your changes use the following. +Make changes to any markdown files in the [`docs/docs-content`](./docs/docs-content/) folder. + + +Start the local development server and preview your changes by navigating to the documentation page you modified. +You can start the local development server by issuing the following command: + ```sh make start ``` -This will open your browser to this address: http://localhost:9000 - -Open `~/Work/librarium/content/docs` in your editor and make changes. They should be synced up in the browser window. - -When you are done with some changes you can create a commit +When you are done with your changes, stage your changes and create a commit ```sh -make commit MESSAGE="" +git add -A && git commit -m "docs: your commit message here" ``` -This will open your browser with the commit. Once the pull request is created a link will be added in the comments to preview the change in a staging environment. - ## Creating Pages The documentation website is structured in a sidebar with main pages and sub-pages. Main pages will contain an overview of the its sub pages. @@ -150,23 +160,69 @@ The index document for a folder follows the naming convention below. Here are so - Named as README (case-insensitive): `docs/Guides/README.mdx` - Same name as the parent folder: `docs/Guides/Guides.md` -#### Referencing a page +### Markdown Links and URLs + +The URL of a page will be composed of the file path to the page in context from the current file. All references to a another documentation page must end with the `.md` extension. Docusaurus will automatically remove the `.md` extension from the URL. The file path is needed for Docuasurus to generate the correct URL for the page when versioning is enabled. -The url of a page will be composed from the path of the file relative to the `content` directory. -**Example** docs/content/1-introduction/1-what-is.md will have http://localhost:9000/introduction/what-is as the url -In markdown you can reference this page relatively to the root of the domain using this syntax: +The following example shows how to reference a page in various scenarios. Assume you have the following folder structure when reviewing the examples below: + +```shell +. +└── docs + └── docs-content + ├── architecture + │   ├── grpc.md + │   └── ip-addresses.md + ├── aws + │   └── iam-permissions.md + ├── clusters + └── security.md +``` + +#### Same Folder + +If you want to link to a file in the same folder, you can use the following syntax: + +```md +![Insert a description here](name_of_file.md) +``` + +Because the file is in the same folder, you do not need to specify the path to the file. Docusaurus will automatically search the current folder for the file when compiling the markdown content. + +So, if you are in the file `grpc.md` and want to reference the file `ip-addresses.md`, you would use the following syntax: + +```md +![A list of all Palette public IP addresses](ip-addresses.md) +``` + +#### Different Folder + +If you want to link to a file in a different folder, you have to specify the path to the file from where the current markdown file is located. + +If you are in the file `security.md` and want to reference the file `iam-permissions.md`, you have to use the following syntax: ```md -[Go to introduction](/introduction/what-is) +![A list of all required IAM permissions for Palette](aws/iam-permissions.md) ``` -You can also reference pages that reside in the document folder, such as index pages. An example is the Dev Engine index page `/docs/04.5-devx.md`. To reference the Dev Engine index page in a documentat page, referce the page by the title. +If you are in the file `grpc.md` and want to reference the file `iam-permissions.md`, you have to use the following syntax: ```md -[Go to Dev Enging](/devx) +![A list of all required IAM permissions for Palette](../aws/iam-permissions.md) ``` + +#### Exceptions + +As of Docusarus `2.4.1`, the ability to reference pages that belong to another plugin is not available. To work around this limitation, URL reference path must be used. + +> [!WARNING] +> Be aware that this approach will break versioning. The user experience will be impacted as the user will be redirected to the latest version of the page. + + +In future releases, Docusaurus will support referencing pages from other plugins. Once this feature is available, we will update the documentation to reflect the changes. + ### Redirects To add a redirect to an existing documentation page you must add an entry to the [redirects.js](/src/shared/utils/redirects.js) file. Below is an example of what a redirect entry should look like. @@ -178,7 +234,7 @@ To add a redirect to an existing documentation page you must add an entry to the }, ``` -#### Multi Object Selector +### Multi Object Selector The Packs integration page and the Service Listings page use a component to display the various offerings. Packs intergations use the `` component, whereas the Service Tiers from App Mode use the `` component. @@ -197,7 +253,7 @@ To add a Service to the Service List complete the following actions: - Populate the page with content. -#### Images or other assets +### Images or other assets All images must reside in the [`assets/docs/images`](./assets/docs/images/) folder. @@ -218,7 +274,7 @@ Image size loading can be customised. You can provide eager-load to images in th ![alt text eager-load](/clusterprofiles.png) ``` -#### Tabs component +### Tabs component To use the tabs component you have to import it from the _shared_ folder @@ -242,7 +298,7 @@ After that, you can use it like this - the values can be one of the tab panel keys - additionally you may refer to different sections from the inner tab using the anchor points(using the #section-1) -#### YouTube Video +### YouTube Video To use a Youtube video us the YouTube component. @@ -251,7 +307,7 @@ In your markdown file, use the component and ensure you specify a URL. ```js ``` -### Points of interest component +### Points of Interest ```js From ce632bbb371351d606c8a126ad88fe664cf0cf43 Mon Sep 17 00:00:00 2001 From: Karl Cardenas Date: Tue, 19 Sep 2023 12:29:44 -0700 Subject: [PATCH 2/4] ci: update version branch PR CI --- .github/workflows/version-branch-update.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/version-branch-update.yaml b/.github/workflows/version-branch-update.yaml index 0f6e95816b..fb4f7eb490 100644 --- a/.github/workflows/version-branch-update.yaml +++ b/.github/workflows/version-branch-update.yaml @@ -58,6 +58,7 @@ jobs: - name: Netlify Build run: | + make versions-ci netlify build --context deploy-preview From 9b6ba699f50e8a300300ccd37165a5c28291c823 Mon Sep 17 00:00:00 2001 From: Karl Cardenas Date: Tue, 19 Sep 2023 14:17:35 -0700 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Rita Watson <117382432+ritawatson@users.noreply.github.com> --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5107758302..1dcd8c6dae 100644 --- a/README.md +++ b/README.md @@ -162,7 +162,7 @@ The index document for a folder follows the naming convention below. Here are so ### Markdown Links and URLs -The URL of a page will be composed of the file path to the page in context from the current file. All references to a another documentation page must end with the `.md` extension. Docusaurus will automatically remove the `.md` extension from the URL. The file path is needed for Docuasurus to generate the correct URL for the page when versioning is enabled. +The doc page URL is composed of the file path to the page in context from the current file. All references to a another documentation page must end with the `.md` extension. Docusaurus will automatically remove the `.md` extension from the URL. The file path is needed for Docuasurus to generate the correct URL for the page when versioning is enabled. @@ -183,7 +183,7 @@ The following example shows how to reference a page in various scenarios. Assume #### Same Folder -If you want to link to a file in the same folder, you can use the following syntax: +To link to a file in the same folder, you can use the following syntax: ```md ![Insert a description here](name_of_file.md) @@ -215,7 +215,7 @@ If you are in the file `grpc.md` and want to reference the file `iam-permissions #### Exceptions -As of Docusarus `2.4.1`, the ability to reference pages that belong to another plugin is not available. To work around this limitation, URL reference path must be used. +As of Docusarus `2.4.1`, the ability to reference pages that belong to another plugin is unavailable. To work around this limitation, use a URL reference path. > [!WARNING] > Be aware that this approach will break versioning. The user experience will be impacted as the user will be redirected to the latest version of the page. From 2fe8e06020a43525c2b6f4e1fe6a757cc4ecd383 Mon Sep 17 00:00:00 2001 From: Karl Cardenas Date: Tue, 19 Sep 2023 14:43:16 -0700 Subject: [PATCH 4/4] docs: updated README with more examples --- README.md | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 1dcd8c6dae..3c560325cf 100644 --- a/README.md +++ b/README.md @@ -161,8 +161,8 @@ The index document for a folder follows the naming convention below. Here are so - Same name as the parent folder: `docs/Guides/Guides.md` ### Markdown Links and URLs - -The doc page URL is composed of the file path to the page in context from the current file. All references to a another documentation page must end with the `.md` extension. Docusaurus will automatically remove the `.md` extension from the URL. The file path is needed for Docuasurus to generate the correct URL for the page when versioning is enabled. +Markdown links use file path references to link to other documentation pages. +The markdown link is composed of the file path to the page in context from the current file. All references to a another documentation page must end with the `.md` extension. Docusaurus will automatically remove the `.md` extension from the URL during the compile. The file path is needed for Docuasurus to generate the correct URL for the page when versioning is enabled. @@ -213,16 +213,43 @@ If you are in the file `grpc.md` and want to reference the file `iam-permissions ![A list of all required IAM permissions for Palette](../aws/iam-permissions.md) ``` +#### A Heading in the Same File + +To link to a heading in the same file, you can use the following syntax: + +```md +[Link to a heading in the same file](#heading-name) +``` + +The `#` symbol is used to reference a heading in the same file. The heading name must be in lowercase and spaces must be replaced with a `-` symbol. Docusaurs by default uses dashes to separate words in the URL. + +#### A Heading in a Different File + +To link to a heading in a different file, you can use the following syntax: + +```md +[Link to a heading in a different file](name_of_file.md#heading-name) +``` +For example, if you are in the file `grpc.md` and want to reference the heading `Palette gRPC API` in the file `security.md`, you would use the following syntax: + +```md +[Link to a heading in a different file](../security.md#palette-grpc-api) +``` +The important thing to remember is that the `#` comes after the file name and before the heading name. + #### Exceptions -As of Docusarus `2.4.1`, the ability to reference pages that belong to another plugin is unavailable. To work around this limitation, use a URL reference path. +As of Docusarus `2.4.1`, the ability to link to documentation pages that belong to another plugin is unavailable. To work around this limitation, reference a documentation page by the URL path versus the file path. + +```md +[Link to a page in another plugin](/api-content/authentication#api-key) +``` > [!WARNING] > Be aware that this approach will break versioning. The user experience will be impacted as the user will be redirected to the latest version of the page. -In future releases, Docusaurus will support referencing pages from other plugins. Once this feature is available, we will update the documentation to reflect the changes. - +In future releases, Docusaurus will support linking pages from other Docusarus plugins. Once this feature is available, this documentation will be updated. ### Redirects To add a redirect to an existing documentation page you must add an entry to the [redirects.js](/src/shared/utils/redirects.js) file. Below is an example of what a redirect entry should look like.