Fix/redo API docs generation

[azeey]

🦟 Bug fix

Summary

This is both a fix and a redo of our API doc generation in preparation for #441. As of #450, the jobs that generate the API docs have been failing with the following error:

2024-06-14T06:21:57.2623277Z #10 37.38 sudo ./aws/install
2024-06-14T06:21:57.9339362Z #10 38.21 You can now run: /usr/local/bin/aws --version
2024-06-14T06:21:58.0848240Z #10 38.21 
2024-06-14T06:21:58.0849021Z #10 38.21 # Configure AWS so that API docs can be uploaded to s3.
2024-06-14T06:21:58.0849924Z #10 38.21 aws configure set aws_access_key_id $1
2024-06-14T06:21:58.3793718Z #10 38.65 aws configure set aws_secret_access_key $2
2024-06-14T06:21:58.8300383Z #10 39.11 aws configure set aws_session_token $3
2024-06-14T06:21:59.2276112Z #10 39.50 
2024-06-14T06:21:59.2277284Z #10 39.50 usage: aws [options] <command> <subcommand> [<subcommand> ...] [parameters]
2024-06-14T06:21:59.2278178Z #10 39.50 To see help text, you can run:
2024-06-14T06:21:59.2278735Z #10 39.50 
2024-06-14T06:21:59.2279090Z #10 39.50   aws help
2024-06-14T06:21:59.2279503Z #10 39.50   aws <command> help
2024-06-14T06:21:59.2280025Z #10 39.50   aws <command> <subcommand> help
2024-06-14T06:21:59.2280548Z #10 39.50 
2024-06-14T06:21:59.2281086Z #10 39.50 aws: error: the following arguments are required: value
2024-06-14T06:21:59.2281774Z #10 39.50 
2024-06-14T06:22:02.4495312Z #10 ERROR: process "/bin/sh -c scripts/install_common_deps.sh $AWS_ACCESS_KEY_ID $AWS_SECRET_ACCESS_KEY $AWS_SESSION_TOKEN" did not complete successfully: exit code: 252

Unfortunately, this is not apparent from looking at https://github.com/gazebosim/docs/actions. I only found out because I was comparing run times with the approach in this PR vs our previous approach and the runtimes after #450 were dramatically reduced.

This also reworks how we generate the docs. Instead of docker files that build the documentation, it uses the containers provided by Github actions. This should overcome the #390 issue we've ran into before. It also uses our new gazebo-setup GitHub action making it possible to build the API docs in parallel bringing the build times to ~5 minutes from ~60 minutes.

Finally, this PR will be used in #441 to deploy the API docs along with the gazebosim.org website.

Checklist

• Signed all commits for DCO
• Added tests
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Consider updating Python bindings (if the library has them)
• codecheck passed (See contributing)
• All tests passed (See test coverage)
• While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

[azeey]

Need to remove this before merge.

[azeey]

Need to remove --dry-run before merge.

[azeey]

cc @Crola1702

[azeey]

@claraberendsen any thoughts why https://github.com/gazebosim/docs/actions/runs/9748558116/job/26904109229?pr=453 is failing with

Run aws-actions/configure-aws-credentials@v4
It looks like you might be trying to authenticate with OIDC. Did you mean to set the `id-token` permission? If you are not trying to authenticate with OIDC and the action is working successfully, you can ignore this message.
Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers

Is it because the PR is from a fork?

[Crola1702]

Looks good. Not using drilled credentials into the dockerfiles is a good improvement to integration with OIDC

[Crola1702]

+1 to using aws cli in github actions

[Crola1702]

Is it because the PR is from a fork?

It might be a reason to fail. We only allow gazebosim/docs repo to authenticate with OIDC here

[azeey]

I'll close this and create a PR from the gazebosim repo.