chore(docs): reorganize docs folder, add 404 checker #2125

leohhhn · 2024-05-16T10:33:16Z

Description

Continuing #1999

Renames the docs with numbers, adds a Go linter and makefile to run it to check for 404 or broken links.

Contributors' checklist...

Added new tests, or not needed, or not feasible
Provided an example (e.g. screenshot) to aid review or the PR is self-explanatory
Updated the official documentation or not needed
No breaking changes were made, or a BREAKING CHANGE: xxx message was included in the description
Added references to related issues and PRs
Provided any useful hints for running manual tests
Added new benchmarks to generated graphs, if any. More info here.

Signed-off-by: moul <94029+moul@users.noreply.github.com>

# Conflicts: # docs/02-getting-started/03-local-setup/browsing-gno-source-code.md # docs/02-getting-started/03-local-setup/browsing-gnoland.md # docs/02-getting-started/03-local-setup/installation.md # docs/02-getting-started/03-local-setup/interacting-with-gnoland.md # docs/04-concepts/stdlibs/events.md

moul · 2024-05-17T18:27:40Z

docs/Makefile

+
+# Build the linter
+build:
+	cd linter && go build -o ./build/linter


Cool that you added a linter. However, please move it to misc/docs-linter.

Keep this Makefile here.

Thank you.

Would be nice to run it from the CI too.

Moved the linter: e7546dd

Adding the linter to the CI seems like it is out of scope for this PR - let's leave it for another one.

Added the linter to the CI: 8fad8c9

moul

Looks good to me.

There is a question on the hierarchy that we need to address later, but this system looks good for both humans and machines, whether on GitHub or from a Go script that would want to generate static pages.

codecov · 2024-05-19T10:44:55Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 54.62%. Comparing base (a85b380) to head (c9f3fa0).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2125      +/-   ##
==========================================
- Coverage   54.64%   54.62%   -0.02%     
==========================================
  Files         578      578              
  Lines       77877    77877              
==========================================
- Hits        42554    42544      -10     
- Misses      32150    32160      +10     
  Partials     3173     3173

Flag	Coverage Δ
contribs/gnodev	`24.24% <ø> (ø)`
contribs/gnofaucet	`14.46% <ø> (ø)`
contribs/gnokeykc	`0.00% <ø> (ø)`
contribs/gnomd	`0.00% <ø> (ø)`
gno.land	`61.65% <ø> (ø)`
gnovm	`60.00% <ø> (ø)`
misc/autocounterd	`0.00% <ø> (ø)`
misc/genproto	`0.00% <ø> (ø)`
misc/genstd	`73.90% <ø> (ø)`
misc/goscan	`0.00% <ø> (ø)`
misc/logos	`17.38% <ø> (-0.31%)`	⬇️
misc/loop	`0.00% <ø> (ø)`
tm2	`54.48% <ø> (-0.03%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

zivkovicmilos

We need to resolve some things before we move forward, please address the comments

zivkovicmilos · 2024-05-23T13:15:32Z

misc/docs-linter/go.mod

+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/peterbourgon/ff/v3 v3.4.0 // indirect


Why do we need to use this package for a single flag?
We can use the standard go flag library for the lint commands

I am using our commands package (github.com/gnolang/gno/tm2/pkg/commands) and I think ff/v3 is a dependency on it. I would keep it in for consistency throughout the codebase and the possibility that we add more flags later, seems like there is no harm in this.

zivkovicmilos · 2024-05-23T13:15:42Z

misc/docs-linter/main.go

+)
+
+var (
+	ErrEmptyPath = errors.New("you need to pass in a path to scan")


Why is this exported?

zivkovicmilos · 2024-05-23T13:16:11Z

misc/docs-linter/main.go

+		commands.Metadata{
+			Name:       "docs-linter",
+			ShortUsage: "docs-linter [flags]",
+			ShortHelp:  "Finds broken 404 links in the .md files in the given folder & subfolders",


Shouldn't this lint, not just find broken links?

In this case, this "linter" is supposed to only check for 404s, as stated in the original PR. Do you think docs-404-checker would be a more appropriate name?

zivkovicmilos · 2024-05-23T13:16:28Z

misc/docs-linter/main.go

+			ShortHelp:  "Finds broken 404 links in the .md files in the given folder & subfolders",
+		},
+		cfg,
+		func(ctx context.Context, args []string) error {


It's funny that the go linter was not run against this code

I ran a linter and fixed the unused variables: fe69c6a

zivkovicmilos · 2024-05-23T13:17:33Z

misc/docs-linter/main.go

+		return err
+	}
+
+	fmt.Printf("Linting %s...\n", abs)


Why not use commands.IO?

It seems to me that fmt is quite more simple and more known, and is a standard library, which is why I opted for it.

zivkovicmilos · 2024-05-23T13:25:11Z

misc/docs-linter/main_test.go

+	}
+}
+
+func removeDir(t *testing.T, dirPath string) func() {


Why not directly call this in the t.Cleanup?

I use the same functionality twice, so I've extracted it to a separate function. I think it makes the code more readable, and this is how I used to implement in in the past based on feedback from the team.

zivkovicmilos · 2024-05-23T13:25:38Z

misc/docs-linter/util.go

@@ -0,0 +1,107 @@
+package main


These funcs should be in the same file as where they're called

I've moved all functions to the main.go file in this commit: 3172ee8

zivkovicmilos · 2024-05-23T13:27:20Z

misc/docs-linter/util.go

+		// Lock the mutex before appending to results
+		lock.Lock()
+		*results = append(*results, fmt.Sprintf("%s (found in file: %s)", url, filePath))
+		lock.Unlock()


You can put this in a defer

I've moved the locks out of this function here: 3172ee8

zivkovicmilos · 2024-05-23T13:27:36Z

misc/docs-linter/util.go

+}
+
+// checkUrl checks if a URL is a 404
+func checkUrl(lock *sync.Mutex, url string, filePath string, results *[]string) error {


Please rewrite this function so it doesn't modify the inputs 🙏

I've purified the function to return an error based on the result, and then modify the array elsewhere: 3172ee8 (#2125)

zivkovicmilos · 2024-05-23T13:29:12Z

misc/docs-linter/main.go

+	)
+}
+
+func execLint(cfg *cfg, ctx context.Context) error {


If this is supposed to be a linting suite for the documentation, then the main run loop shouldn't need to run a single linter, but be able to run multiple ones

Please create some kind of pipeline system 🙏

The idea with this was to only have a link 404 checker. Reference this comment

leohhhn · 2024-06-03T16:00:12Z

I will resolve the merge conflicts after we merge this for consistency

leohhhn · 2024-06-03T16:53:23Z

I've also added a CI workflow but I'm not fully sure I'm doing it right - any inputs would be appreciated.

leohhhn · 2024-06-06T14:01:14Z

Staging is returning a 404:
http://staging.gno.land:26657/
http://rpc.staging.gno.land:26657/

@albttx can you check this out?

moul and others added 6 commits April 29, 2024 17:57

chore: reorganize docs folder with numbered prefixes

0552b37

Signed-off-by: moul <94029+moul@users.noreply.github.com>

rename files

385f3be

add script to link 404

418e871

remove link

da7f493

play around with go linter

42d13d5

github-actions bot assigned leohhhn May 16, 2024

leohhhn changed the title ~~chore: reorganize docs folder with numbered prefixes~~ chore(docs): reorganize docs folder with numbered prefixes May 16, 2024

leohhhn mentioned this pull request May 16, 2024

chore: reorganize docs folder with numbered prefixes #1999

Closed

10 tasks

leohhhn and others added 11 commits May 17, 2024 11:42

save

302b915

Merge branch 'master' into feat/num-docs

3b60caf

Merge branch 'master' into feat/num-docs

88accde

save

c939b2b

fix linter

82e33b2

add makefile

8cdb904

update makefile

0a459ff

cleanup

94b0f5d

add tests

e8bdaae

fix broken link

d4b1462

fix link

12ab737

leohhhn marked this pull request as ready for review May 17, 2024 16:41

leohhhn requested review from a team and moul as code owners May 17, 2024 16:41

leohhhn requested a review from zivkovicmilos May 17, 2024 16:42

leohhhn changed the title ~~chore(docs): reorganize docs folder with numbered prefixes~~ chore(docs): reorganize docs folder, add 404 linter May 17, 2024

moul reviewed May 17, 2024

View reviewed changes

moul approved these changes May 17, 2024

View reviewed changes

move linter

e7546dd

leohhhn requested a review from a team as a code owner May 17, 2024 18:53

leohhhn removed the request for review from a team May 17, 2024 18:53

leohhhn added 3 commits May 17, 2024 20:57

update makefile

0561066

fix all links

6c8ddc5

rm grc721

212d440

make

4fe9883

zivkovicmilos requested changes May 23, 2024

View reviewed changes

leohhhn added 9 commits June 2, 2024 14:33

parallel tests

ca2a606

purify function

3172ee8

var block

12e1b2e

unexport error

8d1533a

errors & defer unlock

7597672

printf

973796d

inline errors

a38e987

remove defer unlock & run go linter

fe69c6a

remove newline

7a63bfa

add CI workflow

8fad8c9

leohhhn and others added 8 commits June 5, 2024 10:12

merge master

38cdcfc

Merge branch 'master' into feat/num-docs

6ab4ea4

switch errors

23008cb

make output nicer, edit error

578735b

nicer output for CI

eebd6c7

remove ...

b5e5971

fix port

fb594f4

rename infra

20495bc

leohhhn changed the title ~~chore(docs): reorganize docs folder, add 404 linter~~ chore(docs): reorganize docs folder, add 404 checker Jun 5, 2024

rename CI

c9f3fa0

leohhhn requested a review from zivkovicmilos June 5, 2024 11:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(docs): reorganize docs folder, add 404 checker #2125

chore(docs): reorganize docs folder, add 404 checker #2125

leohhhn commented May 16, 2024 •

edited

moul May 17, 2024

moul May 17, 2024

leohhhn May 17, 2024

leohhhn Jun 5, 2024

moul left a comment

codecov bot commented May 19, 2024 •

edited

zivkovicmilos left a comment

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024 •

edited

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024 •

edited

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024 •

edited

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024 •

edited

zivkovicmilos May 23, 2024

leohhhn Jun 3, 2024

leohhhn commented Jun 3, 2024 •

edited

leohhhn commented Jun 3, 2024 •

edited

leohhhn commented Jun 6, 2024

chore(docs): reorganize docs folder, add 404 checker #2125

Are you sure you want to change the base?

chore(docs): reorganize docs folder, add 404 checker #2125

Conversation

leohhhn commented May 16, 2024 • edited

Description

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

moul left a comment

Choose a reason for hiding this comment

codecov bot commented May 19, 2024 • edited

Codecov Report

zivkovicmilos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leohhhn Jun 3, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leohhhn Jun 3, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leohhhn Jun 3, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leohhhn Jun 3, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

leohhhn commented Jun 3, 2024 • edited

leohhhn commented Jun 3, 2024 • edited

leohhhn commented Jun 6, 2024

leohhhn commented May 16, 2024 •

edited

codecov bot commented May 19, 2024 •

edited

leohhhn Jun 3, 2024 •

edited

leohhhn Jun 3, 2024 •

edited

leohhhn Jun 3, 2024 •

edited

leohhhn Jun 3, 2024 •

edited

leohhhn commented Jun 3, 2024 •

edited

leohhhn commented Jun 3, 2024 •

edited