Local readthedocs #4542
Merged
Local readthedocs #4542
Conversation
This file contains 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
Use rtds-action instead of yosys-cmd-ref repo. Add rtds_action to docs configuration. Add `.readthedocs.yaml`. Update `DOCS_USAGE_` make target to be able to use pre-generated executables without forcing a remake.
mmicko
approved these changes
Aug 16, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
What are the reasons/motivation for this change?
Yosys ReadtheDocs is currently built from a separate repo, yosys-cmd-ref. This would occasionally lead to problems with people looking at the wrong repository for the documentation source, since yosys-cmd-ref is automatically updated from this repo with the verific runner. This was being done since a portion of the documentation requires yosys to be compiled in order to generate, which would take too long for the ReadtheDocs builder and would generate without verific compatibility which also changes the generated documentation.
Because the verific runner would only update documentation from the main branch, the current setup also makes it more difficult to preview documentation changes for, e.g., yosys PRs. The yosys-cmd-ref repo also ends up with a lot of code-generated images and such which get committed/updated from time to time.
Explain how this is achieved.
This PR provides the necessary framework to allow ReadtheDocs to be built from the Yosys repository directly, making use of the rtds-action to create build artifacts and trigger ReadtheDocs to build using those artifacts; negating the need for a second repository.
If applicable, please suggest to reviewers how they can test the change.
These docs were built from my fork of this repo with all of the expected artifacts (compiled on the standard git runner without verific). And another example demonstrating how pr previews could work with this.
If this PR is passing all checks, it should be safe to merge into main. The current status of the ReadtheDocs integration is that the verific runner builds and uploads the artifact needed, and can trigger the ReadtheDocs webhook to build, but ReadtheDocs rejects building because krys/rtd is not a branch that it recognises as needing to publish. Once this gets merged into main, I suspect that the verific runner will run the merged commit, triggering the webhook from the main branch, which will then update the 'latest' version of the ReadtheDocs. If for some reason that breaks, manually rebuilding on ReadtheDocs will continue to use the yosys-cmd-ref repo.