From 45497722e3338305c9d33a80d2f2c4129414b456 Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Fri, 9 Oct 2026 01:00:01 +0800 Subject: [PATCH 1/2] Update landing pages for reference and how-to --- docs/how-to/index.rst | 19 +++++++-------- docs/reference/cryptographic-overview.rst | 4 ++-- docs/reference/index.rst | 28 ++++++++--------------- 3 files changed, 22 insertions(+), 29 deletions(-) diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 9dbb2c5..241e590 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -9,21 +9,17 @@ How-to guides Manage the full operations lifecycle of the ``cloudflared`` charms, from initial deployment through production maintenance. -DNS and networking ------------------- - -.. toctree:: - :maxdepth: 1 - - Configure DNS - Expose a front-end application - Charm operations ---------------- +Essential operational tasks, such as configuration and backup, during the +usage of Cloudflared charms. + .. toctree:: :maxdepth: 1 + Configure DNS + Expose a front-end application Use the configurator charm Integrate with COS Back up and restore @@ -34,6 +30,11 @@ Charm operations Development and community ------------------------- +If you have encountered any problems while using the Cloudflared charms, +check out the troubleshooting guide. If you have any bug fixes or features +you would like to add to the Cloudflared charms, check our contributing guide +first. + .. toctree:: :maxdepth: 1 diff --git a/docs/reference/cryptographic-overview.rst b/docs/reference/cryptographic-overview.rst index ae14074..a2cbb43 100644 --- a/docs/reference/cryptographic-overview.rst +++ b/docs/reference/cryptographic-overview.rst @@ -1,9 +1,9 @@ .. meta:: - :description: An overview of the cryptographic components used by the Cloudflared charms. + :description: An overview of the security and cryptographic components used by the Cloudflared charms. .. _reference_cryptographic_overview: -Cryptographic overview +Security and cryptographic overview ====================== The charms do not implement cryptographic protocols. Juju protects the tunnel diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 9885155..945fcdf 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -6,15 +6,17 @@ Reference ========= -This section contains technical details about the ``cloudflared`` subordinate -machine charm and the ``cloudflare-configurator`` charm. It documents their -configuration, actions, events, relations, and operational interfaces. +Technical specifications and architectural details about the `cloudflared` +subordinate charm and the `cloudflare-configurator` charm. Useful when you +want to configure or integrate the charms, or just want to learn more +about how the Cloudflared charms work. Charm usage ----------- -The following pages provide reference information for deploying and integrating -the charms. +Operators control charm behavior through configuration options, Juju actions, +and Juju integrations. Learn the inner workings of the charm, which can help +you understand the current charm configuration interface and debug problems. .. vale Canonical.013-Spell-out-numbers-below-10 = NO .. vale Canonical.500-Repeated-words = NO @@ -35,8 +37,8 @@ the charms. Architecture and deployments ---------------------------- -These pages describe the subordinate workload, the configurator, and their -relations to a principal application. +Peek into the design and architecture of the charm, useful if you want to +audit or contribute to the Cloudflared charm project. .. toctree:: :hidden: @@ -44,14 +46,4 @@ relations to a principal application. Charm architecture High-level deployment overview - -Advanced topics ---------------- - -These pages cover cryptographic boundaries. - -.. toctree:: - :hidden: - :maxdepth: 1 - - Cryptographic overview + Security and cryptographic overview From e3a3db53417641c803fe8c4bd2b1f188235fb4f1 Mon Sep 17 00:00:00 2001 From: Weii Wang Date: Fri, 9 Oct 2026 02:18:49 +0800 Subject: [PATCH 2/2] Apply batched suggestions from code review Co-authored-by: Erin Conley --- docs/how-to/index.rst | 10 ++++------ docs/reference/cryptographic-overview.rst | 2 +- docs/reference/index.rst | 6 ++---- 3 files changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 241e590..9269a9f 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -12,8 +12,8 @@ production maintenance. Charm operations ---------------- -Essential operational tasks, such as configuration and backup, during the -usage of Cloudflared charms. +Understanding operational tasks, such as configuration and backup, +is essential to use the Cloudflared charms. .. toctree:: :maxdepth: 1 @@ -30,10 +30,8 @@ usage of Cloudflared charms. Development and community ------------------------- -If you have encountered any problems while using the Cloudflared charms, -check out the troubleshooting guide. If you have any bug fixes or features -you would like to add to the Cloudflared charms, check our contributing guide -first. +Discover how to resolve common deployment issues and contribute +any bug fixes or features to the Cloudflared charms. .. toctree:: :maxdepth: 1 diff --git a/docs/reference/cryptographic-overview.rst b/docs/reference/cryptographic-overview.rst index a2cbb43..6709332 100644 --- a/docs/reference/cryptographic-overview.rst +++ b/docs/reference/cryptographic-overview.rst @@ -4,7 +4,7 @@ .. _reference_cryptographic_overview: Security and cryptographic overview -====================== +=================================== The charms do not implement cryptographic protocols. Juju protects the tunnel credential as a `secret `_, diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 945fcdf..9e1bc3a 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,9 +7,7 @@ Reference ========= Technical specifications and architectural details about the `cloudflared` -subordinate charm and the `cloudflare-configurator` charm. Useful when you -want to configure or integrate the charms, or just want to learn more -about how the Cloudflared charms work. +subordinate charm and the `cloudflare-configurator` charm. Charm usage ----------- @@ -37,7 +35,7 @@ you understand the current charm configuration interface and debug problems. Architecture and deployments ---------------------------- -Peek into the design and architecture of the charm, useful if you want to +Peek into the design and architecture of the charm, which is useful if you want to audit or contribute to the Cloudflared charm project. .. toctree::