-
Notifications
You must be signed in to change notification settings - Fork 355
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore(docs): reorganize docs folder, add 404 checker #2125
base: master
Are you sure you want to change the base?
Conversation
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
docs/Makefile
Outdated
|
||
# Build the linter | ||
build: | ||
cd linter && go build -o ./build/linter |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool that you added a linter. However, please move it to misc/docs-linter
.
Keep this Makefile here.
Thank you.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would be nice to run it from the CI too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added the linter to the CI: 8fad8c9
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
I will resolve the merge conflicts after we merge this for consistency |
I've also added a CI workflow but I'm not fully sure I'm doing it right - any inputs would be appreciated. |
Staging is returning a 404: @albttx can you check this out? |
Can you update this branch with master? Related with #2258 |
Ignore 404 errors when not "localhost". |
- name: Run linter | ||
run: make -C docs/ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- name: Run linter | |
run: make -C docs/ | |
- name: Build docs | |
run: make -C docs/ build | |
- name: Run linter | |
run: make -C docs/ lint |
I am going to give a few comments and maybe help if I can. The structure of the PR is currently like: Our doc reads: | Gno.land's documentation adopts the Diataxis framework, ensuring structured and predictable content. (...) Diataxis is like standard doc, with a clear mental model about it. There's actually a question, by numbering all files and directories are we actually following the guidelines? For example this screenshot from https://diataxis.fr/complex-hierarchies/: Diataxis itself says in the end we can what can do whatever we want. Personally I think:
If we put aside the fact ordering can always be done in the markdown, numbering files introduces problems: Insertion/deletion of a numbered file implies changing references to all subsequent files in the series, in all the docs/ files.
So I suggest to abandon this idea of numbered files. Just for example, the current PR has a file called We usually don't need the numbers. I understand the motivation to order files, but for documentation they should mostly matter for tutorials (you take a lesson with a tutor, since the initiation follows a certain path, numbered files make sense in that case). According to the theory, if we use Diataxis mindfully, our documentation will evolve iteratively, and four solid poles will remain, not necessarily named like this, with the docs/README.md occupying a very neutral place in the middle: I propose the following:
This means we can have that as a starting point.
Next iteration, Also soon enough our docs/README.md will look like this:
WDYT? Leon, I understand you have already gone through a lot of work in this PR. So I hope my comment is not discouraging. I just think numbered file will cost a lot of work in the future; it's not fair to not say anything. So let's discuss it. |
<!-- please provide a detailed description of the changes made in this pull request. --> ## Description This PR cherrypicks the 404 link checker / linter from #2125. <details><summary>Contributors' checklist...</summary> - [x] Added new tests, or not needed, or not feasible - [x] Provided an example (e.g. screenshot) to aid review or the PR is self-explanatory - [x] Updated the official documentation or not needed - [x] No breaking changes were made, or a `BREAKING CHANGE: xxx` message was included in the description - [x] Added references to related issues and PRs - [x] Provided any useful hints for running manual tests - [x] Added new benchmarks to [generated graphs](https://gnoland.github.io/benchmarks), if any. More info [here](https://github.com/gnolang/gno/blob/master/.benchmarks/README.md). </details>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Numbering all the document files and directories seems a good idea to control their order of appearance, but why are some files / directories not yet numbered?
<!-- please provide a detailed description of the changes made in this pull request. --> ## Description This PR cherrypicks the 404 link checker / linter from gnolang#2125. <details><summary>Contributors' checklist...</summary> - [x] Added new tests, or not needed, or not feasible - [x] Provided an example (e.g. screenshot) to aid review or the PR is self-explanatory - [x] Updated the official documentation or not needed - [x] No breaking changes were made, or a `BREAKING CHANGE: xxx` message was included in the description - [x] Added references to related issues and PRs - [x] Provided any useful hints for running manual tests - [x] Added new benchmarks to [generated graphs](https://gnoland.github.io/benchmarks), if any. More info [here](https://github.com/gnolang/gno/blob/master/.benchmarks/README.md). </details>
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...
BREAKING CHANGE: xxx
message was included in the description