Update RTD site

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

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,19 +4,26 @@
 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.**
 
-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/>`_
+This solution provides an abstraction layer over existing Canonical products
+to enable built-in support for 12-factor web applications.
 
-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:
+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.
 
+12-factor charms are aimed at developers who create applications based on the
+`12-factor methodology. <https://12factor.net/>`_ 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 applications built using the following frameworks:
+
+- Flask
 - Django
 - FastAPI
 - Go
@@ -53,55 +60,16 @@ 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
-<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.
-
 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
 ---------------------
@@ -113,7 +81,7 @@ 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!