HTML Json schema docs not updated on deploy

[echoix]

Describe the bug
The latest json schema docs generated by json-schema-for-humans aren't accessible from https://megalinter.github.io .

To Reproduce
Steps to reproduce the behavior:

1. Go to https://megalinter.github.io/latest/contributing/#add-a-new-linter
2. Click on see json schema documentation (https://megalinter.github.io/json-schemas/descriptor.html)
3. Observe in a browser debugger tab that https://megalinter.github.io/json-schemas/descriptor.html generates a 404 and redirects to https://megalinter.github.io/latest/json-schemas/descriptor.html
4. Scroll down to the end, of the page, observe that the date is noted like "Generated using json-schema-for-humans on 2021-01-03 at 19:17:48 +0100"
5. Go in the "linters" property https://megalinter.github.io/latest/json-schemas/descriptor.html#linters and try to find the linter_spdx_license property added in Add license in all linters documentation #977 in November 11 2021, it doesn't exist.
6. If instead of version "latest" in URL, try version "5.7.1" or "5.7.0", or anything from "5.1.0" that should've included this tag (5.8.0 rewrites to latest). https://megalinter.github.io/5.7.1/json-schemas/descriptor.html#linters
7. Try using the "beta" version in the URL https://megalinter.github.io/beta/json-schemas/descriptor.html#linters_items_linter_spdx_license , the date is "Generated using json-schema-for-humans on 2022-02-20 at 10:30:06 +0000". So we know that one of the CI deploys to beta at least.
8. Explore the same problem with the Configuration schema, link on https://megalinter.github.io/latest/configuration/ at "Configuration is assisted with auto-completion and validation in most commonly used IDEs, thanks to JSON schema stored on schemastore.org" for URL https://megalinter.github.io/json-schemas/configuration.html. Note that in this case, it is not the linter_spdx_license to find.

Other implications:

• See that the file https://github.com/megalinter/megalinter/blob/main/megalinter/descriptors/schemas/megalinter-descriptor.jsonschema.json is modified in Github at a date (here: Jan 23, 2022 418d1cf), and the corresponding https://github.com/megalinter/megalinter/blob/main/docs/json-schemas/descriptor.html is at another date (Nov 11, 2021 4aa6dd8) which is both after 2021-01-03 as deployed. Also note that the commit for https://github.com/megalinter/megalinter/blob/main/docs/json-schemas/descriptor.html precedes the addition of the linter_spdx_license later on the same day, as seen on the screenshot below.
• See that the files committed/built in https://github.com/megalinter/megalinter.github.io/, even for latest version in https://github.com/megalinter/megalinter.github.io/blob/gh-pages/latest/json-schemas/descriptor.html (https://github.com/megalinter/megalinter.github.io/blob/a365a3c84b960b7040e9c2fb729829d4a45dba90/latest/json-schemas/descriptor.html), committed yesterday, have the 2021-01-03 date. (Obviously!, that's what we see on the website! However, it helps to rule out the possibility that this wasn't what is hosted.)
  • <p class=generated-by-footer>Generated using <a href=https://github.com/coveooss/json-schema-for-humans>json-schema-for-humans</a> on 2021-01-03 at 19:17:48 +0100</p>
• If you go to https://megalinter.github.io/ and change the docs version at the top, for example to 5.6.0, and go back to https://megalinter.github.io/5.6.0/contributing/#add-a-new-linter, the link for the json schema is still https://megalinter.github.io/json-schemas/descriptor.html which will 404 and redirect to version "latest", which isn't the one selected. Are there other links that override the version selected?

Expected behavior
Have the correct JSON schema built and deployed, and if it is expected, to have the up to date version in the repo, since the jsonschema links back to our file (the json one, not HTML though) in the main branch.

Screenshots
If applicable, add screenshots to help explain your problem.

https://megalinter.github.io/beta/json-schemas/descriptor.html#linters_items_linter_spdx_license :

https://github.com/megalinter/megalinter/commits/main?after=bbac3d189baf2154f77b43aca017f377e97627ab+174&branch=main:

https://github.com/megalinter/megalinter/runs/5046667907?check_suite_focus=true:

Additional context
I tried to investigate the CI workflows, but it quickly became too complicated to understand what is what, and why each of the 26 workflow runs or not.
I suspect that the loss happens with "when" the build_schemas_doc.sh is run in the workflow between the steps, that results in that new file not being included. I'm not sure if the 00.297013 seconds to build that page is normal or not, but for the configuration it is more like 2 seconds, so that makes sense. But in both cases, this file isn't committed in the main repo. The build script that updates everything including the tables doesn't seem to run build_schemas_doc.sh in .automation/build_schemas_doc.sh

[nvuillam]

Good catch @echoix :)

I added JSON Schema HTML doc generation when bash build.sh --doc is called :)

[echoix]

And will this fix the issue that it only built on the beta docs? The build_schemas_doc.sh is still called in a certain way in the workflows. What I understand will happen is that it will run once in the main repo regularly, so in appearance the problem is fixed, but it will run another time with the docs deploy/rebuild, but with the same behaviour that had a flaw (that made it only for beta, but not others), but the problem will be masked (for these two files at least).

Also, what could be the fix for the correct versioning URLs for the schema docs? I see that in the .md files have their links generated by the build.py, but I'm not certain yet if the links rewriting will work for any URL, or this works only for .md files (since there seems to be an additional docs build tool for the release). How should a link be made in the .github/CONTRIBUTING.md file to be rendered correctly in the docs/contributing.md page?

https://github.com/megalinter/megalinter/blob/58f6553472501fcbf0c2d15dc9db9f97be5075a1/.github/CONTRIBUTING.md?plain=1#L81-L96

https://github.com/megalinter/megalinter/blob/58f6553472501fcbf0c2d15dc9db9f97be5075a1/docs/contributing.md?plain=1#L1

[echoix]

In fact, the "fix" doesn't seem to have worked, and a conceptual error caused the rest of the build.sh script ran from the Docker entrypoint with environment variable UPGRADE_LINTERS_VERSION=true to fail.¹ Workflow Auto-Update Linters: https://github.com/megalinter/megalinter/actions/runs/1872786653/workflow

First since there is a cd chained with the AND operator && in cd .automation && bash build_schemas_doc.sh && cd .., the third command which is supposed to restore the state never executes, since there is an error in the middle command.
https://github.com/megalinter/megalinter/blob/261264890ddfd543cffe5d6be37e274a73266649/build.sh#L19-L26
So this explains the last error of Error: Config file 'mkdocs.yml' does not exist., so nothing to do with that error.

To isolate the effects of not restoring the current path when an error occurs, we could use a subshell (calling the cd and the script within parentheses), since there is no getting and setting environment variables involved. Maybe find a way that lets us specify a full path, so it doesn't rely on being relative, but works even when ran from that folder. I'm not quite sure what the good way is.

The main error, why did the middle command fail?
Since we see a line number that is inside of build_schemas_doc.sh, we know that the bash call of build.sh didn't fail.

build_schemas_doc.sh: line 5: generate-schema-doc: command not found
build_schemas_doc.sh: line 8: generate-schema-doc: command not found

We know that generate-schema-doc comes from the python package json-schema-for-humans. json-schema-for-humans is listed in the /requirements.dev.txt file, so installed with ..., or it is installed in .github/workflows/build-deploy-docs.yml or .github/workflows/deploy-RELEASE.yml. But in our case, the error is inside .github/workflows/auto-update-linters.yml but inside the "Collect latest versions and help" step, running inside the container built right above.
https://github.com/megalinter/megalinter/blob/58f6553472501fcbf0c2d15dc9db9f97be5075a1/.github/workflows/auto-update-linters.yml#L61-L65
The requirements.dev.txt is only mentioned in the CONTRIBUTING.md docs to have the tools locally installed. Thus, generate-schema-doc is not found because json-schema-for-humans is not installed (at least explicitly by us, I didn't check the internal python packages installed in the image).

Before looking at where or how to install json-schema-for-humans, let's make sure that the "Auto-Update Linters" workflow NEEDS to build the docs each time. Why does it even need mkdocs-material and run this? Isn't "Auto-Update Linters" try to fetch the new versions for the pull requests?

If it really needs to have the build.sh script run inside the container, then installing json-schema-for-human with pip in entrypoint.sh before/after the tests should do the trick.
https://github.com/megalinter/megalinter/blob/4935667cad3ee17477ff8a13fc8f42177c5f269f/entrypoint.sh#L6-L18

Footnotes

1. https://github.com/megalinter/megalinter/runs/5266190088?check_suite_focus=true
   ↩

[nvuillam]

I now remember why I did not put such generation everywhere... it's because even if the json schema does not change, the generated HTML is different everytime

I will rollback the evolution, as I think most of the times the regeneration is useless... and as the json schema is not versioned (only version in branch main is used), the HTML should be regenerated only when the json is updated

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity.
It will be closed in 14 days if no further activity occurs.
Thank you for your contributions.

If you think this issue should stay open, please remove the O: stale 🤖 label or comment on the issue.