[Docs] Add developer documentation for using/modifying the chrome service

[kaddy645]

Signed-off-by: kaddy645 xdeskart@amazon.com

Description

As a plugin or core dashboards developer, I'd like to have a README for the chrome service to be able to quickly and consistently integrate plugins with the global application chrome.

SC

Issues Resolved

Issue-1857

Check List

• New functionality includes testing.
  • All tests pass
    • yarn test:jest
    • yarn test:jest_integration
    • yarn test:ftr
• New functionality has been documented.
• Commits are signed per the DCO using --signoff

[codecov-commenter]

Codecov Report

Merging #1875 (2695e5b) into main (53e98a6) will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1875      +/-   ##
==========================================
- Coverage   67.51%   67.49%   -0.03%     
==========================================
  Files        3073     3076       +3     
  Lines       59118    59144      +26     
  Branches     8986     8989       +3     
==========================================
+ Hits        39914    39919       +5     
- Misses      17020    17041      +21     
  Partials     2184     2184              

Impacted Files	Coverage Δ
...lication/angular/doc_table/components/table_row.ts	83.09% <0.00%> (-8.46%)	⬇️
src/plugins/discover/public/plugin.ts	1.86% <0.00%> (-0.24%)	⬇️
src/plugins/discover/public/get_inner_angular.ts	81.25% <0.00%> (ø)
...n/components/doc_viewer_links/doc_viewer_links.tsx	100.00% <0.00%> (ø)
...er/public/application/angular/doc_viewer_links.tsx	100.00% <0.00%> (ø)
...cation/doc_views_links/doc_views_links_registry.ts	0.00% <0.00%> (ø)
.../discover/public/opensearch_dashboards_services.ts	66.66% <0.00%> (+1.66%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 53e98a6...2695e5b. Read the comment docs.

[ashwin-pc]

Always lovely to see new docs!

Love the work put in to make it look presentable, but i think that the lack of standardization in markdown is kinda ruining it a little. Given that we dont know what viewer the user will use to read this file, lets make sure it semantically correct? I'm open to suggestions but imo i'd:

• avoid using html in markdown
• use ``` only for multiline code snippets
• use code snippet blocks strictly for code (The code snippet should be copy paste-able)
• make sure that the readme is easily readable without a markdown viewer too

As for the doc itself, the content is good. I'd only like to see more of an abstract of what the service is and does as a whole so that i can decide if its what i want.

[CPTNB]

Thanks for writing this up! I see a few different types of content in this file and I'd like you to tease them into individual files and places.

At the highest level you have general guidance about what the plugin is, why it exists, how it works, and in vague terms how it's used. This is good stuff as an at-a-glance reference to future developers, and I think it's what Josh had in mind when he wrote the original issue.

Next you have more lower level API documentation, and I'm not so excited to see this kind of stuff in this type of document. Personally, I prefer my API docs to be very well structured so that I can quickly scan them to get the information I need. I don't want to scan through a narrative to fish out API info. I'm not sure hand-written API docs is the right way to go anyway, since that sort of thing is easily (at least, more easily) auto-generated and automatically kept up to date.

Last, you have some information about libraries and concepts like Observables. I do think this kind of thing has a place, but I'd like to see it live elsewhere from plugin-specific information.

My guidance would be to coalesce the high level information about the plugin into a few narrative paragraphs at the top of the document, then group the API docs into task driven examples that show code blocks that solve what you think might be common tasks. Then, move the information about libraries and Observables to the more free-form blog docs: https://github.com/CPTNB/opensearch-dashboards-dev-docs

[kaddy645]

@CPTNB I agree with you. Observables and Load-ash should be somewhere else as that info is lang specific. I was just collecting right info so we can divide like you said. I'll remove it from this specific README for now.

[ashwin-pc]

Amazing! thanks

[ananzh]

NIT> some e.g left in the doc.