search

ros-infrastructure / ros_buildfarm

ROS buildfarm based on Docker
Apache License 2.0
82 stars 96 forks source link

Update container image base for doc-related container templates. #884

Closed nuclearsandwich closed 3 years ago

nuclearsandwich commented 3 years ago

Partially addressing #878

doc_create_reconfigure_task

This container is used to bootstrap the creation of doc reconfigure jobs. Changes here aren't likely to be high impact since ros_buildfarm is tested on Focal's python3 version by CI and our local workstations.

doc_independent_task

Container for running doc independent jobs. There's a high likelihood for churn here but the task is currently failing due to changes in pip dependencies.

doc_metadata_task

It does not appear that we have any current doc_metadata jobs on the build farm. Nor does this job appear tested so this change will not break anything immediately but it may break if doc_metadata jobs are reintroduced.

nuclearsandwich commented 3 years ago

Requesting feedback from other maintainers:

In one file I used a template variable to set the OS distribution once and use it everywhere in the template.

  1. Is that preferred compared to hard-coding the value repeatedly or is the hard-coding clearer due to the lack of magic? (example)
  2. Is it still preferred to do even when there's only one instance of the hard-coded distribution name in the template? (example)
  3. In files that aren't Dockerfiles with a FROM ... line does it make sense to set the variable just before first use or at the top of the template?

Please let me know what you think!

tfoote commented 3 years ago

Using the template makes sense. I think that it should be used everywhere. It's a little bit of magic, but if we use it the same way everwhere it should be relatively clear.

I thought about suggesting using Docker ARG to be less "magic" but I think the consistency makes more sense.

nuclearsandwich commented 3 years ago

Using the template makes sense. I think that it should be used everywhere. It's a little bit of magic, but if we use it the same way everwhere it should be relatively clear.

Thanks for the feedback. I'll go ahead and propagate the use of the template variable and pull this out of draft.

nuclearsandwich commented 3 years ago

As a result of this change doc jobs will now be run using Sphinx 4.1.2 rather than 1.1.3 which has a significantly updated theme and presentation. An example of the updated documentation is currently on the staging farm here http://repo.test.ros2.org/docs/independent/api/catkin_pkg/html/index.html.

In addition to the content changes sphinx is also building these files under an html subdirectory instead of directly within the package name.

nuclearsandwich commented 3 years ago

After discussing the changes to documentation in today's meeting offline we reached a consensus to move packages to the rtd theme. Since beginning that work I've realized that we're not very consistent at all with respect to documentation theming within these packages and as a result I think we can de-couple updating the documentation themes and updating the base images. https://github.com/ros-infrastructure/ros_buildfarm_config/pull/211 updates the doc-independent configuration to account for changes between Xenial and Focal and I think they're the only two inter-dependent pull requests related to this change.

nuclearsandwich commented 3 years ago

Build Status is a staging build of doc_independent running with the updated apt and pip dependencies in https://github.com/ros-infrastructure/ros_buildfarm_config/pull/211