Debugging read the docs build flow could be easier

[valentinThomazic]

The build of read the docs has been broken for about a month because of an incorrect configuration and the local build (running make -C docs was also broken during a week.

The local build has been fixed by #2641
The read the docs build still needs fixing (in progress : #2641 #2643).

Currently, the only way I have found to debug efficiently is to fork the cva6 repo and to setup read the docs on the fork.

There is an option in Read the Docs enabling the build on each pull request as a Github action. This would not only make debugging easier but would also prevent merging commits that break the documentation build while providing a preview of what is to be merged when the build is successful.

Here is the (read the docs) documentation about this feature: feature feature configuration

Of course, it is up to OpenHW Group to decide wether they want to do that or not, since this would trigger more builds.

[valentinThomazic]

@MikeOpenHWGroup would you mind taking a look at this issue ?

[MikeOpenHWGroup]

It seems the problem was caused by pull-request #2558, which included this update to .readthedocs.yaml.

Hi @JeanRochCoulon, I am not currently set-up to support the CVA6 RTD flow. Someone with the GitHub handle slgth created the PR above. @valentinThomazic suggested slgth is a person named Simon from Thales SIX, but as they are not a member of this repo I cannot assign this Issue to them.

[JeanRochCoulon]

Simondoes not work anymore on cva6 project, maybe @ASintzoff can have a look from next Monday (oOo currently).

[JeanRochCoulon]

@MikeOpenHWGroup In the meantime, the option pointed by @valentinThomazic can highly prevent such a issue generation. Would it be possible to enable it in ReadTheDocs ?

[MikeOpenHWGroup]

This looks like an ugly problem. There seems to be a very large number of packages required to build the CVA6 documentation.

The ReadTheDocs build reports this error:

<internal:/home/docs/.asdf/installs/ruby/3.3.5/lib/ruby/3.3.0/rubygems/core_ext/kernel_require.rb>:136:in `require': cannot load such file -- asciidoctor-lists (LoadError)

This is very similar (not identical) to the error I get when attempting to build the documentation on my Ubuntu 22.04 Desktop machine:

<internal:/usr/lib/ruby/vendor_ruby/rubygems/core_ext/kernel_require.rb>:85:in `require': cannot load such file -- asciidoctor-lists (LoadError)
Did you mean?  asciidoctor/list
               asciidoctor/cli
               asciidoctor/load

Has anyone gotten this to build successfully on an Ubuntu system?