From c6a9785811687870fc704dabd602344c21be5abf Mon Sep 17 00:00:00 2001 From: Mara3l Date: Wed, 8 Nov 2023 11:06:58 +0100 Subject: [PATCH 1/2] DP-2705: Updating the CONTRIBUTING.md with hugo --- CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a15268dd..fc6563f09 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,6 +64,73 @@ The documentation is deployed using manually triggered GitHub workflows. One logical change is done in one commit. +### Documenting new features + +To document a new feature, you need to create a new `.md` file in one of the subsections. These subsections reresent the left navigation menu and are in a hierarchical directories. + +e.g.: + + administration + ├── organization + │ ├── create_or_update_jwk.md + │ ├── delete_jwk.md + │ └── ... + ├── premissions + │ ├── list_available_assignees.md + │ ├── get_declarative_organization_permissions.md + │ └── ... + └── ... + + +> Note that you would not only need to add new `.md` but also edit the existing `_index.md` in the same directory to add a link to your new method. + +Example: + +Imagine you just created a new method named `super_permissions_method` and would like to document it. + +Steps: + +1. You make sure to properly document your new method in the docstrings. + +1. You create a new file `super_permissions_method.md` in `docs/content/en/docs/administration/permissions/` + + 1. With content: + + ``` + --- + title: "super_permissions_method" + linkTitle: "super_permissions_method" + superheading: "catalog_permission." + weight: 100 + --- + + {{< python "sdk.CatalogPermissionService.super_permissions_method" >}} + + ## Example + ```python + # This method does something very cool, trust me bro + sdk.super_permissions_method(user_id = "demo_user", give_all_permission = True) + ``` + + The `{{< python "PATH" >}}` is a hugo shortcode, that will render the information about the method directly from the docstrings. The `PATH` parameter is represented as a path in the API references with a dot `.` denoting each step. + + So in our example, this is an `sdk` package with the permissions service (`CatalogPermissionService`) and then followed by the actual method (`super_permissions_method`). + + + +1. You update the `_index.md` in the same folder: + + ```diff + * [update_name](./update_name/) + * [update_oidc_parameters](./update_oidc_parameters/) + * [create_or_update_jwk](./create_or_update_jwk/) + * [delete_jwk](./delete_jwk/) + * [get_jwk](./get_jwk/) + * [list_jwks](./list_jwks/) + + * [super_permissions_method](./super_permissions_method/) + ``` + +1. Lastly you contact someone from the documentation team for a proof-read and merge. Your changes should be visible in the preview in the PR job named `Netlify Deploy Preview` ## Run tests Tests use [tox](https://tox.wiki/en/latest/index.html) and [pytest](https://docs.pytest.org/en/6.2.x/contents.html) From 8279b547e28a2d5507e4ec6a6d867d32f9208070 Mon Sep 17 00:00:00 2001 From: Mara3l Date: Wed, 8 Nov 2023 15:56:13 +0100 Subject: [PATCH 2/2] TRIVIAL: updating hugo modules --- docs/go.mod | 2 +- docs/go.sum | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/go.mod b/docs/go.mod index f01cffb6f..95f9ecd56 100644 --- a/docs/go.mod +++ b/docs/go.mod @@ -4,7 +4,7 @@ go 1.20 require ( github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2 // indirect - github.com/gooddata/gooddata-docs-theme v0.0.0-20231026115610-865757c9da13 // indirect + github.com/gooddata/gooddata-docs-theme v0.0.0-20231108114123-c9a40ae4f92a // indirect github.com/google/docsy v0.7.1 // indirect github.com/google/docsy/dependencies v0.7.1 // indirect github.com/twbs/bootstrap v5.3.1+incompatible // indirect diff --git a/docs/go.sum b/docs/go.sum index f4fc7b3c6..7b014edcf 100644 --- a/docs/go.sum +++ b/docs/go.sum @@ -10,6 +10,8 @@ github.com/gooddata/gooddata-docs-theme v0.0.0-20231020110753-c96d5d57bff5 h1:jN github.com/gooddata/gooddata-docs-theme v0.0.0-20231020110753-c96d5d57bff5/go.mod h1:VVNP6Cmo+vC37RD3T/YHjyU/QdqftGY5z4G513LYyrA= github.com/gooddata/gooddata-docs-theme v0.0.0-20231026115610-865757c9da13 h1:s6+8+l46mnvOU0SW3LD8thIBTNpv8xMhXxdJyIk+zbk= github.com/gooddata/gooddata-docs-theme v0.0.0-20231026115610-865757c9da13/go.mod h1:VVNP6Cmo+vC37RD3T/YHjyU/QdqftGY5z4G513LYyrA= +github.com/gooddata/gooddata-docs-theme v0.0.0-20231108114123-c9a40ae4f92a h1:o7IiFfQRujgAMMJVLmsftKBbEInSJhdokqXO/OTvPOs= +github.com/gooddata/gooddata-docs-theme v0.0.0-20231108114123-c9a40ae4f92a/go.mod h1:VVNP6Cmo+vC37RD3T/YHjyU/QdqftGY5z4G513LYyrA= github.com/google/docsy v0.7.1 h1:DUriA7Nr3lJjNi9Ulev1SfiG1sUYmvyDeU4nTp7uDxY= github.com/google/docsy v0.7.1/go.mod h1:JCmE+c+izhE0Rvzv3y+AzHhz1KdwlA9Oj5YBMklJcfc= github.com/google/docsy/dependencies v0.7.1 h1:NbzYKJYMin2q50xdWSUzR2c9gCp7zR/XHDBcxklEcTQ=