Repository navigation
docs: fix docs archiving, fail the build on broken anchors, fix account method summaries - #1728
Merged
Merged
Conversation
…nt method summaries `npm run docs:version` now passes `GIT_REVISION_OVERRIDE` to Docusaurus. Since the move to Docusaurus 3, docusaurus-plugin-typedoc 1.x generates the API pages each time Docusaurus loads its plugins, and `docs:version` loads them. So the archived API pages linked to `develop` instead of the release tag. The old 0.21 plugin generated them only during a build, so the 7.6.4, 8.6.0 and 9.2.1 archives were not affected. Fix the manual archiving steps in `www/README.md`. First empty `www/docs/API` but keep its `.gitkeep`: TypeDoc does not empty this folder, so old pages would end up in the archive. Pass the git revision in the two commands that missed it. Run the build after the archive step, as a link check. Add the step that gives the new version its `banner` entry. Remove `DOCS_ONLY_CURRENT` from `www/docusaurus.config.ts`. It only helped to generate the API pages before an archive, and `docs:version` now does this by itself. Set `onBrokenAnchors` to `throw`. Docusaurus 3 only warns by default. A full build finds no broken anchor in any version today. Remove the 10 `@inheritdoc` tags from `src/account/interface.ts`. TypeDoc replaced the summary, `@returns` and `@remarks` of 9 methods with the ones of the referenced method, so the API docs described `estimateAccountDeployFee` as an INVOKE fee estimate. Each comment already has its own text.
Contributor
|
🎉 This PR is included in version 11.3.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation and Resolution
Follow-up to the 10.8.0 docs archive.
npm run docs:versionarchived API pages that link todevelopinstead of the release tag. Since Docusaurus 3, the TypeDoc plugin regenerates the API pages each time Docusaurus loads its plugins, anddocs:versionloads them without the git revision. The script now passes it, and the manual archiving steps inwww/README.mdare fixed to match.Checking the docs build showed two more problems: broken anchors never failed the build, and 9 account methods showed the description of another method in the API docs.
RPC version (if applicable)
N/A
Usage related changes
AccountInterface/Accountmethods (estimateAccountDeployFee,declare,deploy...) now show their own summary,@returnsand@remarks.@inheritdoctags replaced them with the text of another method (estimateInvokeFee,execute...). No code change.Development related changes
npm run docs:versionpassesGIT_REVISION_OVERRIDE. The[Manual] Documentation Version PRworkflow calls this script, so it is fixed too.www/README.md: manual archiving steps fixed (emptywww/docs/APIbut keep.gitkeep, pass the revision in every command, build after the archive step as a link check, add thebannerstep).www/docusaurus.config.ts:onBrokenAnchors: 'throw'(a full build finds no broken anchor today), andDOCS_ONLY_CURRENTremoved (no use left).Checklist: