From 675f29754b5f5ed9c42bb39cfd201569052d31e9 Mon Sep 17 00:00:00 2001 From: erinecon Date: Thu, 30 Jan 2025 15:03:39 -0500 Subject: [PATCH 01/10] update intro paragraphs --- docs/index.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index d49654d..d56df76 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,17 +6,25 @@ **A simple way to deploy and operate 12-Factor web applications.** -You can use a few simple commands to set up a fully integrated and observable -Kubernetes environment for your web application. This solution, called -12-factor charms, provides an abstraction layer over existing Canonical -products. 12-factor charms are aimed at developers who create applications based -on the `12-factor methodology. `_ +Canonical products contain built-in support for web applications. +This solution, called 12-factor charms, provides an abstraction layer +over existing products to provide this support. -While this page introduces 12-factor charms in the context of -the `Flask framework `_, -the same solution also applies to 12-factor applications built -using the following frameworks: +With a few simple commands, you can set up a fully integrated and observable +Kubernetes environment for your web application. These commands create +production-ready OCI-compliant container images and software operators wrapped +around the container images. From there, you can deploy your web application, +connect it to a database, observe through a Grafana based observability stack, +get ingress and much more. +12-factor charms are aimed at developers who create applications based on the +`12-factor methodology. `_ Developers and operators of +12-factor web applications can take advantage of the 12-factor charm solution +to simplify their operations and easily deploy their applications to production. + +The solution applies to 12-factor applications built using the following frameworks: + +- Flask - Django - FastAPI - Go From 1c78eeb0a07c684c0f1555c67914080cf6338ea3 Mon Sep 17 00:00:00 2001 From: erinecon Date: Thu, 30 Jan 2025 15:04:11 -0500 Subject: [PATCH 02/10] remove section with code --- docs/index.rst | 38 -------------------------------------- 1 file changed, 38 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index d56df76..8ac45cb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,44 +61,6 @@ application to benefit from the entire can be connected to a database, e.g. an HA Postgres, observed through a Grafana based observability stack, get ingress and much more. -Create a complete development environment in a few commands ------------------------------------------------------------ - -Rockcraft natively supports Flask. Production-ready OCI images for your -Flask application can be created using Rockcraft with 3 easy -commands that need to be run in the root directory of the Flask application: - -.. code-block:: bash - - sudo snap install rockcraft --classic - rockcraft init --profile flask-framework - rockcraft pack - -The `full Rockcraft tutorial -`_ for -creating an OCI image for a Flask application takes you from a plain Ubuntu -installation to a production ready OCI image for your Flask application. - -Charmcraft also natively supports Flask. You can use it -to create charms that automate every aspect of your Flask -application's life, including integrating with a database, preparing the tables -in the database, integrating with observability and exposing the application -using ingress. From the root directory of the Flask application, the charm for -the application can be created using 4 easy commands: - -.. code-block:: bash - - mkdir charm & cd charm - sudo snap install charmcraft --classic - charmcraft init --profile flask-framework - charmcraft pack - -The `full getting started tutorial `_ -for creating a charm for a Flask application takes you from a plain Ubuntu -installation to deploying the Flask application on Kubernetes, exposing it using -ingress and integrating it with a database. - Documentation ------------- From f860ba8586ce7abdcea7d793b04948c679182a25 Mon Sep 17 00:00:00 2001 From: erinecon Date: Fri, 31 Jan 2025 13:49:45 -0500 Subject: [PATCH 03/10] add give feedback button --- docs/conf.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 8428368..edd320b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -145,6 +145,7 @@ # # TODO: To customise the directory, uncomment and update as needed. "github_folder": "/docs/", + "github_issues": "https://github.com/canonical/paas-charm/issues", # TODO: To enable or disable the Previous / Next buttons at the bottom of pages # Valid options: none, prev, next, both @@ -321,3 +322,11 @@ latex_config = file.read() latex_elements = ast.literal_eval(latex_config.replace("$PROJECT", project)) + +# By default, the documentation includes a feedback button at the top. +# You can disable it by setting the following configuration to True. +disable_feedback_button = False + +html_js_files = ['header-nav.js'] +if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button: + html_js_files.append('github_issue_links.js') From abfb792b06208f8fcf2feaa7d3fc279fb0725eaf Mon Sep 17 00:00:00 2001 From: erinecon Date: Fri, 31 Jan 2025 14:18:31 -0500 Subject: [PATCH 04/10] add contributing link to home page --- docs/.sphinx/_static/github_issue_links.js | 34 ++++++++++++++++++++++ docs/.sphinx/_static/header-nav.js | 10 +++++++ docs/how-to/contributing.rst | 1 + docs/index.rst | 2 +- 4 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 docs/.sphinx/_static/github_issue_links.js create mode 100644 docs/.sphinx/_static/header-nav.js diff --git a/docs/.sphinx/_static/github_issue_links.js b/docs/.sphinx/_static/github_issue_links.js new file mode 100644 index 0000000..f070603 --- /dev/null +++ b/docs/.sphinx/_static/github_issue_links.js @@ -0,0 +1,34 @@ +// if we already have an onload function, save that one +var prev_handler = window.onload; + +window.onload = function() { + // call the previous onload function + if (prev_handler) { + prev_handler(); + } + + const link = document.createElement("a"); + link.classList.add("muted-link"); + link.classList.add("github-issue-link"); + link.text = "Give feedback"; + link.href = ( + github_url + + "/issues/new?" + + "title=docs%3A+TYPE+YOUR+QUESTION+HERE" + + "&body=*Please describe the question or issue you're facing with " + + `"${document.title}"` + + ".*" + + "%0A%0A%0A%0A%0A" + + "---" + + "%0A" + + `*Reported+from%3A+${location.href}*` + ); + link.target = "_blank"; + + const div = document.createElement("div"); + div.classList.add("github-issue-link-container"); + div.append(link) + + const container = document.querySelector(".article-container > .content-icon-container"); + container.prepend(div); +}; diff --git a/docs/.sphinx/_static/header-nav.js b/docs/.sphinx/_static/header-nav.js new file mode 100644 index 0000000..3608576 --- /dev/null +++ b/docs/.sphinx/_static/header-nav.js @@ -0,0 +1,10 @@ +$(document).ready(function() { + $(document).on("click", function () { + $(".more-links-dropdown").hide(); + }); + + $('.nav-more-links').click(function(event) { + $('.more-links-dropdown').toggle(); + event.stopPropagation(); + }); +}) diff --git a/docs/how-to/contributing.rst b/docs/how-to/contributing.rst index d124f1c..9d3808d 100644 --- a/docs/how-to/contributing.rst +++ b/docs/how-to/contributing.rst @@ -1,5 +1,6 @@ .. Copyright 2025 Canonical Ltd. .. See LICENSE file for licensing details. +.. _how-to-contribute: .. TODO: Replace all mentions of ACME with your project name .. TODO: Update all sections containing TODOs; make sure no TODOs are left diff --git a/docs/index.rst b/docs/index.rst index 8ac45cb..8b95e58 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -83,7 +83,7 @@ fixes and constructive feedback. * `Code of conduct `_ * `Get support `_ * `Join our online chat `_ -* Contribute +* :ref:`Contribute ` * Roadmap Thinking about using 12-Factor charms in your next project? Get in touch! From 77ca4d58295a9d329f82e4cacf65b87d35b6a13b Mon Sep 17 00:00:00 2001 From: erinecon Date: Fri, 31 Jan 2025 14:29:47 -0500 Subject: [PATCH 05/10] update documentation structure --- docs/index.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 8b95e58..a54a17b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -66,12 +66,11 @@ Documentation Documentation for this project is located in a few places: -1. This site: Documentation related to the product +1. This site: Documentation related to the product and development 2. `Rockcraft `_: Documentation related to the OCI image containers 3. `Charmcraft `_: Documentation related to the software operators (charms) -4. Coming soon: Documentation related to development Project and community --------------------- From 9b0041017c5dfdda94657f87da0bf3ac2c8f7725 Mon Sep 17 00:00:00 2001 From: erinecon Date: Tue, 4 Feb 2025 10:24:43 -0500 Subject: [PATCH 06/10] incorporate Daniele's review --- docs/index.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index a54a17b..22caa76 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,25 +4,24 @@ 12-Factor app support in Charmcraft and Rockcraft ================================================= -**A simple way to deploy and operate 12-Factor web applications.** +**The 12-factor charm solution is a simple way to deploy and operate +web applications.** -Canonical products contain built-in support for web applications. -This solution, called 12-factor charms, provides an abstraction layer -over existing products to provide this support. +This solution provides an abstraction layer over existing Canonical products +to enable built-in support for 12-factor web applications. With a few simple commands, you can set up a fully integrated and observable Kubernetes environment for your web application. These commands create production-ready OCI-compliant container images and software operators wrapped around the container images. From there, you can deploy your web application, -connect it to a database, observe through a Grafana based observability stack, -get ingress and much more. +connect it to a database, get ingress and much more. 12-factor charms are aimed at developers who create applications based on the -`12-factor methodology. `_ Developers and operators of -12-factor web applications can take advantage of the 12-factor charm solution -to simplify their operations and easily deploy their applications to production. +`12-factor methodology. `_ Web developers and operators + can take advantage of 12-factor charms to simplify their operations and deploy + their applications to production. -The solution applies to 12-factor applications built using the following frameworks: +The solution applies to applications built using the following frameworks: - Flask - Django From b989fab2e942b507b96509c941a6698e83f10b42 Mon Sep 17 00:00:00 2001 From: erinecon Date: Tue, 4 Feb 2025 10:28:58 -0500 Subject: [PATCH 07/10] fix indentation --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 22caa76..0749e29 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,8 +18,8 @@ connect it to a database, get ingress and much more. 12-factor charms are aimed at developers who create applications based on the `12-factor methodology. `_ Web developers and operators - can take advantage of 12-factor charms to simplify their operations and deploy - their applications to production. +can take advantage of 12-factor charms to simplify their operations and deploy +their applications to production. The solution applies to applications built using the following frameworks: From 0f6c0bd43700b98ac404b8bbaa94dc1c788ae25f Mon Sep 17 00:00:00 2001 From: erinecon Date: Tue, 4 Feb 2025 10:51:29 -0500 Subject: [PATCH 08/10] add entry to changelog --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d246f8a..148cc71 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## v1.1.0 - 2025-02-04 + +### Changes + +* Updated the home page for the Read the Docs site to align closer to the +standard model for Canonical products. + ## v1.1.0 - 2024-12-19 ### Changes From 7b62bd1d05d8d02209da5cc570cc0fcccff0b791 Mon Sep 17 00:00:00 2001 From: erinecon Date: Wed, 5 Feb 2025 14:31:56 -0500 Subject: [PATCH 09/10] incorporate David's review --- docs/index.rst | 43 +++++++++++++++++++------------------------ 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 0749e29..f859412 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,36 +4,31 @@ 12-Factor app support in Charmcraft and Rockcraft ================================================= -**The 12-factor charm solution is a simple way to deploy and operate -web applications.** +**Charmcraft and Rockcraft natively support a simple way +to deploy and operate 12-Factor web applications.** -This solution provides an abstraction layer over existing Canonical products -to enable built-in support for 12-factor web applications. +This support makes it easy to utilize existing Canonical products, +such as databases, ingress and observability, in web applications. +Flask, Django, FastAPI and Go are currently supported with additional +frameworks coming soon. With a few simple commands, you can set up a fully integrated and observable Kubernetes environment for your web application. These commands create -production-ready OCI-compliant container images and software operators wrapped -around the container images. From there, you can deploy your web application, -connect it to a database, get ingress and much more. +production-ready OCI-compliant container images for your web application and +software operators wrapped around the container images. From there, you can +deploy your web application, connect it to a database, add ingress and +observability and much more. -12-factor charms are aimed at developers who create applications based on the +The solution is aimed at developers who create applications based on the `12-factor methodology. `_ Web developers and operators -can take advantage of 12-factor charms to simplify their operations and deploy +can take advantage of the solution to simplify their operations and deploy their applications to production. -The solution applies to applications built using the following frameworks: - -- Flask -- Django -- FastAPI -- Go -- Spring Boot (coming soon) - The foundations: Juju, charms and rocks --------------------------------------- -The 12-factor charm solution uses and combines capabilities from the following -Canonical products: +The 12-factor web application solution uses and combines capabilities from the +following Canonical products: - `Juju `_ is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management @@ -58,7 +53,7 @@ Encapsulating the original 12-factor application in a charm allows your application to benefit from the entire `charm ecosystem `_, meaning that the app can be connected to a database, e.g. an HA Postgres, observed through a Grafana -based observability stack, get ingress and much more. +based observability stack, add ingress and much more. Documentation ------------- @@ -74,9 +69,9 @@ Documentation for this project is located in a few places: Project and community --------------------- -12-Factor charms are a member of the Ubuntu family. This is an open source -project that warmly welcomes community projects, contributions, suggestions, -fixes and constructive feedback. +12-Factor web support in Charmcraft and Rockcraft is a member of the Ubuntu family. +This is an open source project that warmly welcomes community projects, contributions, +suggestions, fixes and constructive feedback. * `Code of conduct `_ * `Get support `_ @@ -84,7 +79,7 @@ fixes and constructive feedback. * :ref:`Contribute ` * Roadmap -Thinking about using 12-Factor charms in your next project? Get in touch! +Thinking about using this solution in your next project? Get in touch! .. toctree:: From e188791cb17b0cc2a0f8011689eb3247f7f2fbe8 Mon Sep 17 00:00:00 2001 From: erinecon Date: Wed, 5 Feb 2025 14:37:06 -0500 Subject: [PATCH 10/10] fix changelog entry --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 148cc71..177062d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changes * Updated the home page for the Read the Docs site to align closer to the -standard model for Canonical products. + standard model for Canonical products. ## v1.1.0 - 2024-12-19