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?

[JeanRochCoulon]

Hi Mike,
After discussion with @cathales, the library asciidoctor-lists need to be installed to make Ruby work.
This can be done by executing "gem install asciidoctor-lists" for Ubuntu systems. Can you try on your own?
If it works, this installation should be done on ReadThedocs severs, using Gemfile (as requirements file for python) can be a solution.

[ASintzoff]

I think the root cause is that asciidoctor-lists gem is not part of dependencies/Gemfile in riscv-isa-manual repository.

I just create an issue (riscv/riscv-isa-manual#1811) and a pull request (riscv/riscv-isa-manual#1812).

Hopefully the pull request will be merged and after that, we will need to update the riscv-isa-manual submodule.

[MikeOpenHWGroup]

Thanks for the clue about installing asciidoctor-lists. I was unable to translate the error messages into that simple command. So, after installing asciidoctor-lists it was simply a question of installing all the other dependencies and I can now build the documentation on my desktop Ubuntu 22.04 machine.

The number of dependencies is large:

$ sudo apt-get install ruby
$ sudo apt install ruby-dev
$ sudo gem install asciidoctor-lists
$ sudo npm install -g bytefield-svg
$ sudo npm i wavedrom-cli -g
$ sudo apt install openjdk-17-jdk
$ pip install rstcloth
$ pip install mako
$ pip install mdutils

There are a number of requirements.txt files in the CVA6 repo, but none of them mention all of these. They are specified in the riscv-isa-manual repo (in dependencies/apt_packages.txt and dependencies/Gemfile), but these are not easy to find, and some of these are pretty significant (e.g. ruby and java) so I would recommend we create our own, comprehensive requirements.txt file and not depend on risv-isa-config to do it for us.

In any case, I can now build the documentation locally:

$ cd ~/GitHubRepos/openhwgroup/cva6/master/docs
$ make
$ firefox _build/index.html &

This "works" in that there are no errors and the documentation appears to build correctly. However, there is a very large set of warnings which you can see in the attached logfile.

make.log

[cathales]

André’s pull request has been merged so we can update our submodule now and the automatic build should work.
@ASintzoff do you think that we should add riscv-isa-manual to dependabot’s watchlist or update manually?

@MikeOpenHWGroup I am not in favor of repeating things. Maybe https://github.com/openhwgroup/cva6/blob/master/docs/README.md can point to these dependency files?
There are probably commands to issue from the riscv-isa-manual folder that will install everything automatically, we should probably mention them.

[ASintzoff]

Please, no automatic update of riscv-isa-manual as modifications can break our documentation build. A manual update is currently under internal review.

The commands to install dependencies are available in .readthedocs.yaml.

[MikeOpenHWGroup]

Noticed a small typo that breaks the build. Check out #2725. With that fix, the docs build for me again.

[ASintzoff]

The log files of Read The Docs are available at https://app.readthedocs.com/projects/openhw-group-cva6-user-manual/builds/
This can help to understand what is failing during the documentation build.

Whatever the suggestion done by @valentinThomazic in this issue regarding enabling documentation generation on each PR could be very useful.
@MikeOpenHWGroup, any opinion on this?

[MikeOpenHWGroup]

Whatever the suggestion done by @valentinThomazic in this issue regarding enabling documentation generation on each PR could be very useful.

Do you mean creating a github action to launch a build of the documentation as a gating check for all pull-requests to the master branch? We could do that as long as the Thales team agrees. I would recommend closing this issue and creating another issue to discuss that specific topic.