docs: move shares README to godoc #842
Conversation
Codecov Report
@@ Coverage Diff @@
## main #842 +/- ##
=======================================
Coverage 25.63% 25.63%
=======================================
Files 75 75
Lines 9279 9279
=======================================
Hits 2379 2379
Misses 6677 6677
Partials 223 223 Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. |
|
Sounds good, we can wait for Evan's review. To clarify |
|
Interesting, thanks, didn't know we were publishing docs |
There was a problem hiding this comment.
I'm unsure of this suggestion, so please feel free to ignore or modify:
From my own personal workflow, I appreciate seeing markdown files in github/text editors. Markdown files are also easier to edit than go comments and all of our other docs just use markdown. Using godocs is also super legit. Do we know of a way to do both, have a markdown file that gets pushed to go docs? if not nbd, we can just use godocs or maybe include a readme that links to the godocs?
|
I'd rather read and edit Markdown than Godoc comments so I agree with your concern. It seems like a README.md is preferable for developers contributing to this repo but Godoc comments are preferable for developers using the share package as a dependency because the Godoc comment will be more discoverable than a README.md in the share package. I'm not opposed to a README.md in the share package that links to the Godoc comments but I'm more inclined to copy celestia-node and include a section like https://github.com/celestiaorg/celestia-node#package-specific-documentation in our root README.md because that's more discoverable Update: disregard, it looks like a README surfaces in Godocs. Example: https://pkg.go.dev/github.com/celestiaorg/celestia-app@v0.7.0-rc5/pkg/shares#section-readme |
Inspired by https://github.com/celestiaorg/celestia-node#package-specific-documentation Addresses #842 (review) We can keep the share docs in Godoc form or move them back to README.md form because both will render in https://pkg.go.dev/github.com/celestiaorg/celestia-app/pkg/shares
Inspired by https://github.com/celestiaorg/celestia-node#package-specific-documentation Addresses #842 (review) We can keep the share docs in Godoc form or move them back to README.md form because both will render in https://pkg.go.dev/github.com/celestiaorg/celestia-app/pkg/shares
Motivated by celestia-node's [package-specific-documentation](https://github.com/celestiaorg/celestia-node#package-specific-documentation), I opted to move the shares package `README.md` to godoc. Some changes were necessary because godoc doesn't support all Markdown features. Also, I updated "message start" terminology to use "sequence start" because it applies to non-message shares. ## Screenshot <img width="560" alt="Screen Shot 2022-10-05 at 10 43 10 PM" src="https://user-images.githubusercontent.com/3699047/194202854-682e044a-3c5f-4f09-bbe3-6c8b74625f05.png">
Inspired by https://github.com/celestiaorg/celestia-node#package-specific-documentation Addresses celestiaorg#842 (review) We can keep the share docs in Godoc form or move them back to README.md form because both will render in https://pkg.go.dev/github.com/celestiaorg/celestia-app/pkg/shares
Motivated by celestia-node's package-specific-documentation, I opted to move the shares package
README.mdto godoc. Some changes were necessary because godoc doesn't support all Markdown features. Also, I updated "message start" terminology to use "sequence start" because it applies to non-message shares.Screenshot