Guide refactoring and new tutorials #2579

AlianBenabdallah · 2022-08-19T15:51:52Z

Closes: #2578 and #2474

Status

Ready for review.

You might find some typos.
I feel like there might be room for improvements in :

The Configuration section (5.1). We can build a table with every parameter and their description but it will have to be maintained up to date.
Some content in Relaying (5.4.5) is very useful and would deserve more visibility. Perhaps we could split this section.
We do not mention account_sequence_mismatch anywhere in the guide.

IMPORTANT: I could not try the Production tutorial (section 3.4) as it involves production chains and real coins.

Description

This PR reorganizes the guide, adds new tutorials and adds a Grafana template.

PR author checklist:

Added changelog entry, using unclog.
Added tests: integration (for Hermes) or unit/mock tests (for modules).
Linked to GitHub issue.
Updated code comments and documentation (e.g., docs/).
Tagged one reviewer who will be the one responsible for shepherding this PR.

Reviewer checklist:

Reviewed Files changed in the GitHub PR explorer.
Manually tested (in case integration/unit/mock tests are absent).

…bsection

AlianBenabdallah · 2022-08-30T12:48:50Z

I think the PR is ready for review. You might find some typos even though I used a tool to automatically correct small mistakes and to fix broken links.

I feel like there might be room for improvements in :

The Configuration section (5.1). We can build a table with every parameter and their description but it will have to be maintained up to date.
Some content in Relaying (5.4.5) is very useful and would deserve more visibility. Perhaps we could split this section.
We do not mention account_sequence_mismatch anywhere in the guide.

It is also important to note that I could not try the Production tutorial (section 3.4) as it involves production chains and real coins.

seanchen1991

The diagrams you added look awesome! Thanks so much for adding those Ali 🙂

A bit of an aside, but I learned recently that you can create anchors in your code and then include them in mdbook (it doesn't even require plugins or anything extra). This way, we could present config files and code snippets using actual files that live in the guide/ directory and probably hook them up with a CI job that validates the configs/snippets so that they'll at least always remain valid in the guide.

guide/src/tutorials/local-chains/add-a-new-relay-path.md

seanchen1991 · 2022-08-30T17:15:35Z

guide/src/tutorials/production/start-relaying.md

+
+- In a new terminal, run `hermes start &> hermes.log`. 
+
+If the command runs successfully, you should be able to see the metrics panels displaying data on the Grafana Dashboard and you should also be able to see the logs on the `Logs` panel at the top of the dashboard. You can also explore them on the `explore` page.


Would it be possible to add images of the dashboard so that readers can get a better understanding of this?

It is possible but I can't run the tutorial with Cosmoshub and Osmosis as I would need tokens from both chains. If I run it locally, it will display every metrics with a label chain=ibc-0 and chain=ibc-1 instead of cosmoshub-4 and osmosis-1.

AlianBenabdallah · 2022-08-31T08:51:45Z

A bit of an aside, but I learned recently that you can create anchors in your code and then include them in mdbook (it doesn't even require plugins or anything extra).

Thank you for catching these mistakes and for your suggestion. I think we could also use mdbook-template to create only a single file / command.

I am in the process of integrating mdbook-template to the guide.

AlianBenabdallah · 2022-08-31T11:49:36Z

A bit of an aside, but I learned recently that you can create anchors in your code and then include them in mdbook (it doesn't even require plugins or anything extra). This way, we could present config files and code snippets using actual files that live in the guide/ directory and probably hook them up with a CI job that validates the configs/snippets so that they'll at least always remain valid in the guide.

@seanchen1991 I am currently using mdbook-template to replace most commands by templates. We could use a script to automatically generate those templates from the actual commands but I think it would belong to another PR.

seanchen1991 · 2022-08-31T13:20:33Z

I didn't know about mdbook-templates; it seems like it will make keeping the guide in sync with the code base somewhat easier 🙂

seanchen1991

The guide looks to be a lot more fleshed out! The organization and flow of it also makes a lot more sense 🙂

I especially like the new sections that demonstrate the wrong way to do something for educational purposes. Thank you so much for putting in such a huge amount of work on this ❤️

I'll make a new issue with further polishing tasks such as further integration with mdbook-template, as well as adding images of Grafana templates and things like that. I think we can merge in these changes as-is 🙂

Co-authored-by: Sean Chen <seanchen11235@gmail.com>

AlianBenabdallah · 2022-08-31T13:43:38Z

I especially like the new sections that demonstrate the wrong way to do something for educational purposes. Thank you so much for putting in such a huge amount of work on this ❤️

Thank you so much for this message and thank you for helping me a lot through this task ❤️.

I'll make a new issue with further polishing tasks such as further integration with mdbook-template, as well as adding images of Grafana templates and things like that. I think we can merge in these changes as-is 🙂

I already started to manually add template files. I can finish it by tomorrow (or tonight if I am fast). We can add a script to automatically generate the template files from the commands in another PR.

…s into ali/refactor_guide

AlianBenabdallah · 2022-08-31T15:39:09Z

I used templates in the tutorials but using templates in the Commands Reference looks much more complex. Let's leave it to another PR.

* Modified the file structure + SUMMARY.md + Intro * rename grafana template + move feature matrix * populating section troubleshooting * rename quick_start to quick-start, add manifest-path to alias, new subsection * more renaming * draft description for every section page * fix typo * more reorganization * fix issues * add new commands * wrap up the first tutorial * topology defined * progress on the more-chain tutorial * chart update * progress on the second tutorial * more progress on tutorial 2 * finished 2nd tutorial (might need debugging) * fix packet filters * whatever blocs me from switching branches * add docker image, prometheus config and grafana template updated * tools description * fix grafana template * progress + fixed typos * almost done * more progress * more progress * end of the production tutorial * correct many typos * more fixed typos + additional pages * fixed tutorial * fix current version * removal of identifiers section * fix typo * add next steps to most pages + ## Sections to supersections * finished concurrent tutorial * new note * finished intro page * small improvements + removal of help session in the commit before this one * fix grafana instructions + update grafana template * more typos fixed * fix broken links * tons of broken links fixed * even more broken links * every broken link * fix a lot of typos * fix more things * doc update * Fix link that didn't render in README * Proofread pass over tutorials * mdbook-template exampleé * version with mdbook-template * templates up to 3.2.1 * modify create channel new client command * fix broken link * Suggested review Co-authored-by: Sean Chen <seanchen11235@gmail.com> * first tutorial using mdbook * templates up to 3.3.2 * templates up to 3.3.4 * every tutorial with templates * hardcode versions in dockerfile * github action for mdbook-template Co-authored-by: Sean Chen <seanchen11235@gmail.com>

ali added 2 commits August 19, 2022 17:14

Modified the file structure + SUMMARY.md + Intro

505334e

rename grafana template + move feature matrix

e721f4c

AlianBenabdallah added I: documentation Internal: improvements or additions to documentation O: usability Objective: cause to improve the user experience (UX) and ease using the product I: guide Internal: issues with the Hermes guide labels Aug 19, 2022

AlianBenabdallah added this to the v1.1 milestone Aug 19, 2022

ali added 8 commits August 19, 2022 18:39

populating section troubleshooting

8eb821c

rename quick_start to quick-start, add manifest-path to alias, new su…

ce6de6d

…bsection

more renaming

6f32439

draft description for every section page

7674f84

fix typo

f6747ea

more reorganization

3eee817

fix issues

1454caf

add new commands

184515d

AlianBenabdallah mentioned this pull request Aug 23, 2022

Fix guide commands #2585

Merged

7 tasks

ali added 7 commits August 23, 2022 12:39

wrap up the first tutorial

26e2d47

topology defined

2938dc4

progress on the more-chain tutorial

d89f624

chart update

4fc520a

progress on the second tutorial

2be1496

more progress on tutorial 2

10b90ea

finished 2nd tutorial (might need debugging)

14672d7

romac changed the title ~~New guide~~ Guide refactoring and new tutorials Aug 25, 2022

ali added 7 commits August 25, 2022 11:28

fix packet filters

1cd032c

whatever blocs me from switching branches

43fcd75

add docker image, prometheus config and grafana template updated

0818308

tools description

58e6c3a

fix grafana template

91e1372

progress + fixed typos

0914dd3

almost done

4c3c3c8

merge conflict

b5e1203

AlianBenabdallah self-assigned this Aug 30, 2022

seanchen1991 added 2 commits August 30, 2022 10:26

Fix link that didn't render in README

bc2398e

Proofread pass over tutorials

f28bdf9

seanchen1991 reviewed Aug 30, 2022

View reviewed changes

ali added 4 commits August 31, 2022 12:23

mdbook-template exampleé

18357b9

version with mdbook-template

9d47fa7

templates up to 3.2.1

09e0f90

modify create channel new client command

4cf773a

AlianBenabdallah marked this pull request as draft August 31, 2022 11:31

fix broken link

daeb911

seanchen1991 approved these changes Aug 31, 2022

View reviewed changes

Suggested review

ab1ba7c

Co-authored-by: Sean Chen <seanchen11235@gmail.com>

ali added 7 commits August 31, 2022 16:05

first tutorial using mdbook

82b62a5

Merge branch 'ali/refactor_guide' of github.com:informalsystems/ibc-r…

b00705c

…s into ali/refactor_guide

templates up to 3.3.2

e3d6a6c

templates up to 3.3.4

30dd7b8

every tutorial with templates

05c8a56

hardcode versions in dockerfile

cb971c7

github action for mdbook-template

e7be4ad

AlianBenabdallah marked this pull request as ready for review August 31, 2022 15:41

seanchen1991 merged commit 2818df7 into master Aug 31, 2022

seanchen1991 deleted the ali/refactor_guide branch August 31, 2022 15:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Guide refactoring and new tutorials #2579

Guide refactoring and new tutorials #2579

AlianBenabdallah commented Aug 19, 2022 •

edited

Loading

AlianBenabdallah commented Aug 30, 2022 •

edited

Loading

seanchen1991 left a comment •

edited

Loading

seanchen1991 Aug 30, 2022

AlianBenabdallah Aug 31, 2022

AlianBenabdallah commented Aug 31, 2022 •

edited

Loading

AlianBenabdallah commented Aug 31, 2022

seanchen1991 commented Aug 31, 2022

seanchen1991 left a comment

AlianBenabdallah commented Aug 31, 2022

AlianBenabdallah commented Aug 31, 2022


		- In a new terminal, run `hermes start &> hermes.log`.

		If the command runs successfully, you should be able to see the metrics panels displaying data on the Grafana Dashboard and you should also be able to see the logs on the `Logs` panel at the top of the dashboard. You can also explore them on the `explore` page.

Guide refactoring and new tutorials #2579

Guide refactoring and new tutorials #2579

Conversation

AlianBenabdallah commented Aug 19, 2022 • edited Loading

Status

Description

PR author checklist:

Reviewer checklist:

AlianBenabdallah commented Aug 30, 2022 • edited Loading

seanchen1991 left a comment • edited Loading

Choose a reason for hiding this comment

seanchen1991 Aug 30, 2022

Choose a reason for hiding this comment

AlianBenabdallah Aug 31, 2022

Choose a reason for hiding this comment

AlianBenabdallah commented Aug 31, 2022 • edited Loading

AlianBenabdallah commented Aug 31, 2022

seanchen1991 commented Aug 31, 2022

seanchen1991 left a comment

Choose a reason for hiding this comment

AlianBenabdallah commented Aug 31, 2022

AlianBenabdallah commented Aug 31, 2022

AlianBenabdallah commented Aug 19, 2022 •

edited

Loading

AlianBenabdallah commented Aug 30, 2022 •

edited

Loading

seanchen1991 left a comment •

edited

Loading

AlianBenabdallah commented Aug 31, 2022 •

edited

Loading