docs: template for spec and initial files

[evan-forbes]

Overview

This is just the initial "get the ball rolling" on the specs by adding the template @staheri14 created in #1818 and the initial links to each README in the state machine code as discussed in the internal audit/spec call. This is not intented to be the final structure 🙂

closes #1818, #1555

Checklist

• New and updated code has appropriate documentation
• New and updated code has new and/or updated testing
• Required CI checks are passing
• Visual proof for any user facing features like CLI or documentation updates
• Linked issues closed with keywords

[github-actions]

PR Preview Action v1.4.4
🚀 Deployed preview to https://celestiaorg.github.io/celestia-app/pr-preview/pr-1856/
on branch gh-pages at 2023-05-31 16:02 UTC

[rootulp]

I think we should add the new pages to these pages so that they show up in the PR preview: https://celestiaorg.github.io/celestia-app/pr-preview/pr-1856/

• https://github.com/celestiaorg/celestia-app/blob/main/specs/src/README.md?plain=1
• https://github.com/celestiaorg/celestia-app/blob/main/specs/src/SUMMARY.md?plain=1

My impression was that the short term approach would be to copy + paste the contents of the x/module/README.md to specs/src/mint/module.md and in x/module/README.md have a link to the corresponding page in the specs. If that's the case, spec owners can do that after this merges.

[codecov-commenter]

Codecov Report

Merging #1856 (c017e9f) into main (1ecde6d) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #1856   +/-   ##
=======================================
  Coverage   21.82%   21.82%           
=======================================
  Files         116      116           
  Lines       13247    13247           
=======================================
  Hits         2891     2891           
  Misses      10065    10065           
  Partials      291      291           

[staheri14]

My impression was that the short term approach would be to copy + paste the contents of the x/module/README.md to specs/src/mint/module.md and in x/module/README.md have a link to the corresponding page in the specs. If that's the case, spec owners can do that after this merges.

[Suggestion] If we proceed with this approach, then each spec owner would be able (in addition to copying the old content from the x/module/README.md) to organize the content of the respective file based on the specs template.

[staheri14]

LGTM! 🚀
[Optional] We could have a README file specifically for the specs folder. This README can provide high-level information about the structure of the specs folder, including details on how the specs are formatted. It can include a link to the template that the specs should follow, as well as any other relevant information (which can be kept concise for now and expanded upon later through iteration).

[evan-forbes]

My impression was that the short term approach would be to copy + paste the contents of the x/module/README.md to specs/src/mint/module.md and in x/module/README.md have a link to the corresponding page in the specs.

this is what was originally suggested iirc, but I believe @MSevey suggested that we have the opposite mapping for now until we have some other setup that pulls the relevant readme's into that package. I'm open to suggestions about structure

[MSevey]

My impression was that the short term approach would be to copy + paste the contents of the x/module/README.md to specs/src/mint/module.md and in x/module/README.md have a link to the corresponding page in the specs.

this is what was originally suggested iirc, but I believe @MSevey suggested that we have the opposite mapping for now until we have some other setup that pulls the relevant readme's into that package. I'm open to suggestions about structure

my initial naive thought was that we could just update the summary page to link to the actual pkg READMEs https://github.com/celestiaorg/celestia-app/blob/main/specs/src/SUMMARY.md?plain=1

then you the specs folder is really just a shell.

a second naive approach was that instead of the spec README having a link to the pkg README, the spec file itself was a symbolic link to the README in the pkgs.

Both are totally untested, so feel free to completely ignore me and do what makes the most sense to the team :-)

I was mostly just throwing out alternatives to help reduce duplication.

[liamsi]

I like what @MSevey suggested for the following reasons:

• less duplication / no copy paste necessary
• cosmos devs can still find docs where they would expect them (under x/modulename)
• my intuition is that devs will feel more responsibility over the specs/docs if they are in the same directory as the code (might be completely wrong about this too)

[cmwaters]

my initial naive thought was that we could just update the summary page to link to the actual pkg READMEs https://github.com/celestiaorg/celestia-app/blob/main/specs/src/SUMMARY.md?plain=1

I think we should just do this. Having directories with a file that just links to another file seems misleading. In the overview page where you lay out the contents of the spec, I would just do direct links to the readmes in the packages/modules we have. For the stuff that doesn't have a clear directory, like block validity rules, I would add those pages to the spec directory

[rootulp]

I think we should either:
Option A: keep https://github.com/celestiaorg/celestia-app/blob/main/specs/src/README.md up to date with https://github.com/celestiaorg/celestia-app/blob/main/specs/src/SUMMARY.md
Option B: delete https://github.com/celestiaorg/celestia-app/blob/main/specs/src/README.md

Note we need to keep SUMMARY.md b/c https://rust-lang.github.io/mdBook/guide/creating.html#summarymd

[evan-forbes]

note: added all the sdk modules we're using clsoing #1555

[evan-forbes]

@rootulp sorry, was just in the of refactoring when you reviewed. the readme should be up to date now

[evan-forbes]

@cmwaters @MSevey
cool good idea, moved from having specific directories for state modules to just having links. I think the original thinking was that we would fill out more high level specs beyond the standard cosmos-sdk documentation, hence the specific directories for when we fill those out, but keeping those specs in their respective modules and linking in the readme as needed makes a lot of sense

[cmwaters]

I do echo Rootul's concern of having a duplicated README.md and a SUMMARY.md but other than that am happy with this initial direction

[cmwaters]

Is this really a module?

[evan-forbes]

I was tempted to not include it, but yeah it is and it can result in non-determinism for starting the genesis so I decided to include it.

https://github.com/celestiaorg/cosmos-sdk/blob/24903f4a983911f708fbf138a895ea4abc5dc752/x/genutil/module.go#L45-L53

[evan-forbes]

I do echo Rootul's concern of having a duplicated README.md and a SUMMARY.md but other than that am happy with this initial direction

I agree and we can definitely change this stucture in the future, it doesn't make any sense to have two. I think this is just an mdbook thing, which we could also change.

This markdown file must be named SUMMARY.md.

https://rust-lang.github.io/mdBook/format/summary.html