Cookbook documentation

[BlaineHeffron]

What

Adds a Cookbook.md file which gets copied over by stellar-docs for documentation on common stellar use cases.

Why

Easy for stellar-cli maintainers to add "cookbook" entries from the stellar-cli repo.

Close #1438

Known limitations

N/A

[leighmcculloch]

Given the cookbook is hand written, it might be best committed to the stellar-docs repo. The main reason we keep the full help markdown here is it is generated from code, but for the cookbook it is not generated. And all other hand written documentation simply lives in stellar-docs.

[leighmcculloch]

If we can write a test that executes the cookbook top-to-bottom to confirm the commands are valid, that's definitely a reason to keep it here though. Is that something we're planning to do as part of this change?

[BlaineHeffron]

I agree regarding the manually written stuff. Originally I had just added these entries to https://developers.stellar.org/docs/build/guides/cli but Jane wanted to have a document that lives on the the CLI github. See discussion here - stellar/stellar-docs#840

I think that adding a test that runs through the commands is a great idea. My question is, it seems like the cli guide has quite a bit of "cookbook" style documentation already; should we add all of those to this document as well so that they all get tested? We could even auto generate those entries from this document.

[leighmcculloch]

I think that adding a test that runs through the commands is a great idea. My question is, it seems like the cli guide has quite a bit of "cookbook" style documentation already; should we add all of those to this document as well so that they all get tested? We could even auto generate those entries from this document.

Agreed, the existing guides are already a cookbook, and these don't need to be two different efforts. +1 to combining them, hosting them all here so we can run tests on them. It would be good if we could keep them as separate files and not bundle them all into a single file.

@janewang wdyt?

[janewang]

It makes sense to move the guides to the CLI repo to run tests. Then copy over to the final guides to the dev docs for visibility.

[janewang]

Blocked by this bug #1557

[janewang]

Hi @BlaineHeffron, the issue that is blocking this PR is closed.