docs(auth): improve signer docs with devsite refs

[alvarowolfx]

Improvements to Signer docs:

• Add warning about using Service Account
• Link to what is ADC.

Towards #3645

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.77%. Comparing base (aba90f6) to head (d2bb629).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4201      +/-   ##
==========================================
+ Coverage   94.76%   94.77%   +0.01%     
==========================================
  Files         187      187              
  Lines        7106     7106              
==========================================
+ Hits         6734     6735       +1     
+ Misses        372      371       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coryan]

Can you use markdown inside the <div>?

Suggested change

	//! <div class="warning">
	//! <strong>Caution:</strong> Service account keys are a security risk if not managed correctly.
	//! See <a href="https://docs.cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys">
	//! Best practices for managing service account keys</a> for more information.
	//! <div class="warning">
	//! **Caution:** Service account keys are a security risk if not managed correctly.
	//! See [Best practices for managing service account keys] for more information.

And then add this at the bottom?

/// [Best practices for managing service account keys]: https://docs.cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys

[alvarowolfx]

it doesn't render markdown inside divs

[coryan]

Apparently it can happen with some caveats:

https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#adding-a-warning-block

[alvarowolfx]

oh, interesting, I tried to use the markdown syntax and just assumed was not supported. Will try that trick from the docs

[alvarowolfx]

hmm, I wonder if there a version of rust that supports that, because I tried this and it is still not rendering:

//! <div class="warning">
//!
//!     **Caution:** Service account keys are a security risk if not managed correctly.
//!     See [Best practices for managing service account keys] for more information.
//!
//! </div>

[coryan]

To get closer to the rendering at the docs.rs site use:

rustyp update nightly
cargo install --locked cargo-docs-rs
cargo +nightly docs-rs --package google-cloud-storage

But then again, it is not that important.

[coryan]

To get closer to the rendering at the docs.rs site use:

rustyp update nightly
cargo install --locked cargo-docs-rs
cargo +nightly docs-rs --package google-cloud-storage

But then again, it is not that important.