Update RTD site

CHANGELOG.md

@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## v1.2.0 - 2025-02-06
 
+### Changes
+
+* Updated the home page for the Read the Docs site to align closer to the
+  standard model for Canonical products.
+
+## v1.2.0 - 2025-02-06
+
 ### Added
 
 * Added support for tracing web applications using an integration with

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);
+};

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();
+    });
+})

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')

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

docs/index.rst

@@ -4,29 +4,31 @@
 12-Factor app support in Charmcraft and Rockcraft
 =================================================
 
-**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. <https://12factor.net/>`_
-
-While this page introduces 12-factor charms in the context of
-the `Flask framework <https://flask.palletsprojects.com/en/stable/>`_,
-the same solution also applies to 12-factor applications built
-using the following frameworks:
-
-- Django
-- FastAPI
-- Go
-- Spring Boot (coming soon)
+**Charmcraft and Rockcraft natively support a simple way
+to deploy and operate 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 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.
+
+The solution is aimed at developers who create applications based on the
+`12-factor methodology. <https://12factor.net/>`_ Web developers and operators
+can take advantage of the solution to simplify their operations and deploy
+their applications to production.
 
 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 <https://juju.is>`_ is an open source orchestration engine for software
   operators that enables the deployment, integration and lifecycle management
@@ -51,72 +53,33 @@ Encapsulating the original 12-factor application in a charm allows your
 application to benefit from the entire
 `charm ecosystem <https://charmhub.io/>`_, 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.
-
-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
-<https://documentation.ubuntu.com/rockcraft/en/latest/tutorial/flask.html>`_ 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 <https://canonical-charmcraft.
-readthedocs-hosted.com/en/latest/tutorial/flask/>`_
-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.
+based observability stack, add ingress and much more.
 
 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 <https://documentation.ubuntu.com/rockcraft/en/latest/>`_:
    Documentation related to the OCI image containers
 3. `Charmcraft <https://canonical-charmcraft.readthedocs-hosted.com/en/stable/>`_:
    Documentation related to the software operators (charms)
-4. Coming soon: Documentation related to development
 
 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 <https://ubuntu.com/community/ethos/code-of-conduct>`_
 * `Get support <https://discourse.charmhub.io/>`_
 * `Join our online chat <https://matrix.to/#/#12-factor-charms:ubuntu.com>`_
-* Contribute
+* :ref:`Contribute <how-to-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::