Skip to content
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

Better docs builds #4563

Merged
merged 17 commits into from
Sep 3, 2024
Merged

Better docs builds #4563

merged 17 commits into from
Sep 3, 2024

Conversation

KrystalDelusion
Copy link
Member

@KrystalDelusion KrystalDelusion commented Aug 22, 2024

What are the reasons/motivation for this change?

  • The current setup for rtds_action doesn't work locally.
  • There are also cases where ReadtheDocs will build before the docs artifact is ready and upload an incomplete version of the documentation.

Explain how this is achieved.

  • Gate rtds_action behind checks for both READTHEDOCS and GITHUB_TOKEN environment variables. This also has some changes to (better) support building on mac and other small formatting fixes.
  • Update .readthedocs.yaml to fail if sphinx raises any warnings, notably because it's missing files. This also involves fixing the couple of warnings that were still popping up. I also ended up splitting the prepare-docs job from the test-verific in order to better control when the job would run. There is an extra change so that todos appear in preview builds but not in release builds.

If applicable, please suggest to reviewers how they can test the change.
Run make docs locally. Check docs-previewtest tag (https://yosyshq.readthedocs.io/projects/yosys/en/docs-previewtest/).

@KrystalDelusion
Copy link
Member Author

As a note, I was running export "LC_ALL=C" make docs PYTHON=python. The LC_ALL was to resolve an error about an unsupported locale when using sphinx, and the PYTHON=python was because I was getting an error when trying to python3/pip3 install about it being externally managed and suggesting using a venv instead, whereas python/pip didn't... Not sure if either of those are because mac, or specific to my partner's machine/setup.

Based on the docs-test-fork PR branch, includes PR preview announcement, linking to the relevant tyrtd page
Swap `cp -u` for `rsync -t`.
Drop the workaround to get the list of dot files after copying them, and instead just run the makefile twice.
Swap `$(wildcard **/*.x)` for `$(shell find . -name *.x)`,
Which is what the comment said, but the code didn't match.
Trigger on main, on a branch called `docs-preview*`, or on any tag.
Latest still gets -dev, but if it's a docs preview use the tag/branch name.
@KrystalDelusion KrystalDelusion force-pushed the krys/better_rtds_action branch from acb608f to ecff434 Compare August 26, 2024 22:23
Fix outstanding sphinx warnings;
- Change mycells.lib to use `text` parsing instead of (currently) unsupported `Liberty`.
- Remove unused `troubleshooting.rst`, moving the todo into the index.
@KrystalDelusion KrystalDelusion force-pushed the krys/better_rtds_action branch 5 times, most recently from fcb94ba to 977118a Compare September 2, 2024 23:24
Docs jobs should not skip on concurrent jobs (in case a non-docs job is already
running, such as when a commit has been tagged for docs-preview). However, a
successful `test-verific` can allow for a future docs job to skip testing and go
straight to the preview.
@KrystalDelusion KrystalDelusion changed the title Fix local builds of docs Better docs builds Sep 3, 2024
@mmicko mmicko merged commit 9fca352 into main Sep 3, 2024
30 checks passed
@mmicko mmicko deleted the krys/better_rtds_action branch September 3, 2024 07:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants