docs(updates): update precommit and fix whitespace, comments/updates/… #289

Avantol13 · 2024-12-09T16:55:34Z

…suggestions throughout

I only truly reviewed gen3/docs/gen3-resources. All other changes are automated by precommit to fix whitespace.

Link to JIRA ticket if there is one:

New Features

Breaking Changes

Bug Fixes

Improvements

update precommit and fix whitespace
various grammar updates
various comments/suggestions
various reformatting/rewording

Dependency updates

Deployment changes

…suggestions throughout

formatting update

* Update using-api.md change the code so users are not told to paste their API key into their code, but instead reference the file * Update using-api.md update environment reference to https://gen3.datacommons.io

Avantol13 · 2024-12-12T18:59:37Z

gen3/docs/gen3-resources/glossary.md

-The Gen3 workspace token service acts as an OIDC client which acts on behalf of users to request refresh tokens from Fence. This happens when a user logs into a workspace from the browser. WTS then stores the refresh token for that user, and manages access tokens and refresh tokens for workers that belong to specific users in the workspace.
+A simple list of most relevant microservices are included below.  For a description of each service and links to their respective repositories please visit the [Developer's Guide][Microservices].
+
+* Aggregated Metadata Service (AggMDS)


This isn't a separate service, so I wouldn't include it in this list. This case is actually what makes it difficult to describe our offerings as services rather than APIs. There's only 1 service, the MDS, which exposes the MDS API and the aggMDS API.

re: this -- although it's technically not a separate service, i think we think about and talk about it as though it is a separate service. especially because they have the 2 endpoints. maybe we can talk more about that in a asterisky way -- but it feels like something that should be treated differently, even if technically it isn't

Would you be comfortable with it if we explained a bit more that ack-chu-ally, it's all part of the metadata service -- but it is kinda special, and has its own endpoint?

Notably -- arguing more for you -- there is only one Helm chart (called metadata) that covers both of these

I guess I would ask whether everything an operator might need to know is located in the MDS repo. I do see an AggMDS link within that repo: https://github.com/uc-cdis/metadata-service/blob/865f83015f7a30a35b58d00054a1950eb0ecb48b/docs/agg_mds.md

If, however, the AggMDS repo (https://github.com/uc-cdis/agg-metadata) contains documentation that is useful to someone creating a mesh then we should link to it separately in some way.

In other words, my goal for listing out services is to make sure operators or developers who need to have access to repo-specific documentation can find what they need.

Upon further discussion, we will remove the AggMDS repo since the code governing the AggMDS is actually all within the MDS repo.

gen3/docs/gen3-resources/user-guide/search.md

Avantol13 · 2024-12-12T19:05:56Z

gen3/docs/gen3-resources/user-guide/using-api.md

@@ -49,7 +46,7 @@ import json, requests
 api = "https://gen3.datacommons.io"
 key_file = "/put_path_to/credentials.json"

-# Read the key from the file and 
+# Read the key from the file and


incomplete sentence

Avantol13 · 2024-12-12T19:07:25Z

gen3/docs/gen3-resources/developer-guide/microservices.md

@@ -5,7 +5,6 @@ Gen3 features and functionality are enabled by independent and modular microserv
 While the average user does not need to know the details and names of each microservice, if you are interested in adding new features or modifying your Gen3 system in some way it may be helpful to have a deeper understanding of a specific microservice.  We have included brief descriptions below along with a link to their documentation in GitHub.

 ## [Aggregated Metadata Service (AggMDS)][aggmds github]


I still worry about having this separated from the MDS. At least we should put them together

AggMDS was consolidated under MDS

Co-authored-by: Alexander VanTol <[email protected]>

michaelfitzo · 2024-12-11T14:56:03Z

gen3/docs/gen3-resources/user-guide/access-data.md

I updated the authorization section, but it would be good for you to review again.

michaelfitzo · 2024-12-11T15:26:58Z

gen3/docs/gen3-resources/user-guide/portal.md

I think I have addressed most of your comments although I left the potentially duplicated information for the Query Page

michaelfitzo · 2024-12-11T15:27:55Z

gen3/docs/gen3-resources/glossary.md

I removed the description of the microservices in the glossary to avoid the problem of the content getting out of sync with the developer's guide

michaelfitzo · 2024-12-11T15:43:32Z

gen3/docs/gen3-resources/index.md

michaelfitzo · 2024-12-11T22:50:48Z

gen3/docs/gen3-resources/user-guide/search.md

I have mentioned this workflow (discovery -> access approval -> exploration), but with the caveat that not every system will have a discovery page so it is not universal. I also mentioned that the SDK has a CLI.

michaelfitzo · 2024-12-12T18:40:37Z

gen3/docs/gen3-resources/user-guide/using-api.md

Change to API instructions were made

michaelfitzo · 2024-12-12T19:48:59Z

gen3/docs/gen3-resources/glossary.md

-The Gen3 workspace token service acts as an OIDC client which acts on behalf of users to request refresh tokens from Fence. This happens when a user logs into a workspace from the browser. WTS then stores the refresh token for that user, and manages access tokens and refresh tokens for workers that belong to specific users in the workspace.
+A simple list of most relevant microservices are included below.  For a description of each service and links to their respective repositories please visit the [Developer's Guide][Microservices].
+
+* Aggregated Metadata Service (AggMDS)


I guess I would ask whether everything an operator might need to know is located in the MDS repo. I do see an AggMDS link within that repo: https://github.com/uc-cdis/metadata-service/blob/865f83015f7a30a35b58d00054a1950eb0ecb48b/docs/agg_mds.md

If, however, the AggMDS repo (https://github.com/uc-cdis/agg-metadata) contains documentation that is useful to someone creating a mesh then we should link to it separately in some way.

In other words, my goal for listing out services is to make sure operators or developers who need to have access to repo-specific documentation can find what they need.

michaelfitzo · 2024-12-13T15:14:20Z

gen3/docs/gen3-resources/glossary.md

-The Gen3 workspace token service acts as an OIDC client which acts on behalf of users to request refresh tokens from Fence. This happens when a user logs into a workspace from the browser. WTS then stores the refresh token for that user, and manages access tokens and refresh tokens for workers that belong to specific users in the workspace.
+A simple list of most relevant microservices are included below.  For a description of each service and links to their respective repositories please visit the [Developer's Guide][Microservices].
+
+* Aggregated Metadata Service (AggMDS)


Upon further discussion, we will remove the AggMDS repo since the code governing the AggMDS is actually all within the MDS repo.

docs(updates): update precommit and fix whitespace, comments/updates/…

b753e88

…suggestions throughout

Avantol13 requested review from a team as code owners December 9, 2024 16:55

Avantol13 and others added 7 commits December 9, 2024 10:57

Merge branch 'master' into docs/updates

67be033

Merge branch 'master' into docs/updates

ef28883

Update architecture.md

c25658e

formatting update

response to review

3bce57b

Update using-api.md (#292)

72a48fc

* Update using-api.md change the code so users are not told to paste their API key into their code, but instead reference the file * Update using-api.md update environment reference to https://gen3.datacommons.io

remove comment

812310b

Merge branch 'master' into docs/updates

28c024d

Avantol13 commented Dec 12, 2024

View reviewed changes

gen3/docs/gen3-resources/user-guide/search.md Outdated Show resolved Hide resolved

Avantol13 commented Dec 12, 2024

View reviewed changes

gen3/docs/gen3-resources/user-guide/search.md Outdated Show resolved Hide resolved

Avantol13 commented Dec 12, 2024

View reviewed changes

smvgarcia and others added 4 commits December 12, 2024 13:24

Update gen3/docs/gen3-resources/user-guide/search.md

ac4c53f

Co-authored-by: Alexander VanTol <[email protected]>

Update gen3/docs/gen3-resources/user-guide/search.md

b13146e

Co-authored-by: Alexander VanTol <[email protected]>

Update using-api.md

82663cb

removing AggMDS repo from docs

bf3d7c8

michaelfitzo approved these changes Dec 13, 2024

View reviewed changes

michaelfitzo merged commit df04533 into master Dec 13, 2024
2 checks passed

michaelfitzo deleted the docs/updates branch December 13, 2024 15:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(updates): update precommit and fix whitespace, comments/updates/… #289

docs(updates): update precommit and fix whitespace, comments/updates/… #289

Avantol13 commented Dec 9, 2024 •

edited

Loading

Avantol13 Dec 12, 2024

smvgarcia Dec 12, 2024

smvgarcia Dec 12, 2024

smvgarcia Dec 12, 2024

michaelfitzo Dec 12, 2024

michaelfitzo Dec 13, 2024

Avantol13 Dec 12, 2024

michaelfitzo Dec 13, 2024

Avantol13 Dec 12, 2024

michaelfitzo Dec 13, 2024

michaelfitzo Dec 11, 2024

michaelfitzo Dec 11, 2024

michaelfitzo Dec 11, 2024

michaelfitzo Dec 11, 2024

michaelfitzo Dec 11, 2024

michaelfitzo Dec 12, 2024

michaelfitzo Dec 12, 2024

michaelfitzo Dec 13, 2024

		@@ -5,7 +5,6 @@ Gen3 features and functionality are enabled by independent and modular microserv
		While the average user does not need to know the details and names of each microservice, if you are interested in adding new features or modifying your Gen3 system in some way it may be helpful to have a deeper understanding of a specific microservice. We have included brief descriptions below along with a link to their documentation in GitHub.

		## [Aggregated Metadata Service (AggMDS)][aggmds github]

docs(updates): update precommit and fix whitespace, comments/updates/… #289

docs(updates): update precommit and fix whitespace, comments/updates/… #289

Conversation

Avantol13 commented Dec 9, 2024 • edited Loading

New Features

Breaking Changes

Bug Fixes

Improvements

Dependency updates

Deployment changes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Avantol13 commented Dec 9, 2024 •

edited

Loading