docs: Add external property back to compose and add swarm secrets example using compose

[deahtstroke]

Description

Added back the attribute external in the /reference/compose/secrets section with a warning that this attribute is only available for Docker Swarm. Additionally, I added a small toy reference example to the section "Defining and using Secrets in compose files" and moved the section outside of the "Examples" section. The reason why I did this is because I noticed the Examples are all runnable steps that showcase concrete usage of secrets, the example I added is just a skeleton/reference to how they should be used in conjunction with docker secret create..., not a true able-to-run example like the ones below. I also changed the hyperlink from /reference/compose-file/legacy-versions.md to /reference/compose-file/secrets.md.

A few caveats that I wasn't sure about when writing this:

• I'm not sure if using the "[!NOTE]" in the attributes list is the approach maintainers and writers might favor and I can change it accordingly
• I'd love to hear feedback on moving "Defining and using secrets in compose files" outside of "Examples" due to my reasoning above

Edit:
I'm also not opposed to making a fully working example using compose, stack and secrets and putting the section back under Examples

Related issues or tickets

#25491

Reviews

• Technical review
• Editorial review
• Product review

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	4b2d876
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a8febceae16b90008890366
😎 Deploy Preview	https://deploy-preview-25522--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[aevesdocker]

Thanks @deahtstroke. The engine/swarm/secrets/ addition makes sense to me and I'm fine with that part.

Could you drop the reference/compose/secrets change, though? Plain docker compose errors with unsupported external secret on that attribute since it requires swarm, so even with the [!NOTE] caveat, documenting it on the generic Compose reference risks readers copying it outside a swarm context and hitting an unexplained CLI error. That page's audience is mostly plain-Compose users. Let's keep external scoped to the swarm-specific page where it's actually valid, and leave the generic reference as-is.

[deahtstroke]

Thanks for the Review! Yeah I hard agree on that rationale, which also makes sense as to why the original issues about the external option being confusing for compose users were opened in the first place. I removed the changes to /content/reference/compose-file/secrets.md 😄

[aevesdocker]

Thank you @deahtstroke!