update doxygen version

[burlen]

Details

• Read the Docs project URL: https://readthedocs.org/projects/teca
• Build URL (if applicable): https://readthedocs.org/projects/teca/builds/13651770/
• Read the Docs username (if applicable):

Expected Result

With the versions of Doxygen that ship with Ubuntu 20.04 and other recent OS's Doxygen parses our code correctly.

Actual Result

On readthedocs.org (and other Ubuntu 18.04 hosts) Doxygen crashes on our code with the following error:

Preinput buffer overflow, can't enlarge buffer because scanner uses REJECT

See: https://readthedocs.org/api/v2/build/13651770.txt

We desperately need to have the version of doxygen updated in our readthedocs.org environment or to be running on a newer OS image such as 20.04. Can you please help us accomplish one of these?

[burlen]

I see that Ubuntu 20.04 is available here: https://github.com/readthedocs/readthedocs-docker-images

I think that will solve my problem but I don't know how to configure our readthedocs.org project to use that version of Ubuntu. Is it possible?

[astrojuanlu]

Hi @burlen, thanks for using Read the Docs!

You should be able to use that image by putting

build:
  image: testing

in your .readthedocs.yaml, see https://docs.readthedocs.io/en/stable/config-file/v2.html#build-image

[burlen]

@astrojuanlu Thanks for the quick reply. That's great news!

I tried adding the build section as suggested, Unfortunately no change. I'm pasting my yml below. Also, I've added lines to my conf.py to cat /etc/issue and doxygen --version to verify which OS and Doxygen we are getting. After adding the build section, we are still on Ubuntu 18.04.5 LTS and Doxygen 1.8.13.

Let me know if you have any idea why id didn't work?

version: 2

build:
  image: testing

sphinx:
  configuration: doc/rtd/conf.py

python:
  version: 3.8
  install:
    - requirements: doc/rtd/requirements.txt

[stsewd]

Looks like our settings are one version behind

readthedocs.org/readthedocs/settings/base.py

Lines 494 to 496 in c941723

	'readthedocs/build:stable': DOCKER_IMAGE_SETTINGS.get('readthedocs/build:5.0'),
	'readthedocs/build:latest': DOCKER_IMAGE_SETTINGS.get('readthedocs/build:6.0'),
	'readthedocs/build:testing': DOCKER_IMAGE_SETTINGS.get('readthedocs/build:7.0'),

/cc @humitos

[humitos]

@stsewd Hrm, I also thought we were using 8.0 (running Ubuntu 20.04) for testing at this point. I think we prepared everything to do the upgrade (that's why README says that) but then we realized that it could break builds, we started talking about the new docker image structure to avoid these breaks but we haven't implemented that structure yet.

[drewcassidy]

Is there any ETA on a 20.04 docker image being available?

[burlen]

Yes, an ETA would be very helpful for planning purposes. It would be extremely helpful if this issue (or is there another one I should watch?) were updated when 20.04 is available.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[burlen]

This issue still needs to be resolved, because of the old doxygen/Ubuntu version we are running it manually and uploading a tarball. Very much less than ideal. I had hoped for a quick resolution to this since it had seemed like a newer ubuntu version was in the works. any progress? eta?

[stsewd]

We are planning on releasing a new docker image in the following weeks, but not sure if it includes a new testing image as well, /cc @humitos

[burlen]

@stsewd thanks for the update. The newer doxygen package versions in 20.04 will resolve my issue. I don't expect any breakages re other packages/versions. I am happy to switch as soon as it is available.

[humitos]

We are planning on releasing a new docker image in the following weeks, but not sure if it includes a new testing image as well, /cc @humitos

We are still discussing how to do the rollout with a newer Ubuntu version. I don't think we will upgrade testing to Ubuntu 20.04 LTS, tho. We should implement https://docs.readthedocs.io/en/stable/development/design/build-images.html directly, instead.

[vhirtham]

@burlen No need to wait for a new image with Ubuntu 20.04 if you only need it for a higher Doxygen version. I also had issues with my documentation that builds fine on my local machine with version 1.8.17 but isn't compatible with Doxygen 1.8.13. However, I found a simple solution:
Since Doxygen is now available on conda-forge and readthedocs has conda support, you can use all newer doxygen versions (1.8.13 up to 1.9.1) in your RTD build. Just add the following line to your RTD config file:

conda:
  environment: <DIRECTORY>/environment.yml

Now create the file <DIRECTORY>/environment.yml in your repo with the following content:

name: RTD
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.8
  - doxygen=<VERSION>

RTD should now build your Doxygen documentation using the version you specified. 😉

[njzjz]

Since Doxygen is now available on conda-forge and readthedocs has conda support...

Got a memory error, though...

Command killed due to excessive memory consumption

[astrojuanlu]

@njzjz Please send us a support request to enable mamba for your project :)

[astrojuanlu]

For subscribers of this issue, we have now shipped a new build image based on Ubuntu 20.04. You can opt in by writing this on your .readthedocs.yaml:

build:
  os: "ubuntu-20.04"
  tools:
    python: "3"

With that, you will get the latest Doxygen version on this Ubuntu version, which is doxygen 1.8.17. Please let us know if you have any trouble with it.

Read more on our docs.

[burlen]

@astrojuanlu @humitos This worked for me! Thank you so much!