updates to product RTD site (#21)

* Update home page descriptions

* update working directory for periodic style checks

* fix header to fit in margin

* edits to home page text

* update changelog

* update custom wordlist

* update home page to be product-specific

* update changelog

* put wordlist in alphabetical order

* update links to be unique

* update home page and wordlist

* update home page

* more small edits

* remove docs table

* update header

.github/workflows/periodic-style-checks.yml

@@ -11,7 +11,7 @@ jobs:
     defaults:
       run:
         shell: bash
-        working-directory: "sp-docs"
+        working-directory: "docs"
     steps:
       - uses: actions/checkout@v4
       - name: Run vale

CHANGELOG.md

@@ -9,12 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## v1.1.0 - 2024-12-19
 
+### Changes
+
+Updated the home page for the Read the Docs site to provide relevant information
+about the project.
+
+## v1.1.0 - 2024-12-19
+
 ### Added
 
 * Added support for async workers for Gunicorn services (flask and Django).
 
 ## v1.0.0 - 2024-11-29
 
+## 2024-11-29
+
 ### Changes
 
 * Added a `docs` folder to hold the

docs/.custom_wordlist.txt

@@ -1,2 +1,7 @@
 Charmcraft
+FastAPI
+lifecycle
+natively
+OCI
+Postgres
 Rockcraft

docs/.sphinx/_templates/header.html

@@ -10,17 +10,13 @@
     <ul class="p-navigation__links" role="menu">
 
       <li>
-        <a class="p-logo" href="https://{{ product_page }}" aria-current="page">
+        <a class="p-logo" href="" aria-current="page">
           <img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
           <div class="p-logo-text p-heading--4">{{ project }}
           </div>
         </a>
       </li>
 
-      <li class="nav-ubuntu-com">
-        <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
-      </li>
-
       <li>
         <a href="#" class="p-navigation__link nav-more-links">More resources</a>
         <ul class="more-links-dropdown">
@@ -54,4 +50,4 @@
 
     </ul>
   </div>
-</header>
+</header>

docs/conf.py

@@ -26,7 +26,7 @@
 #
 # TODO: Update with the official name of your project or product
 
-project = "12-Factor app support in Charmcraft and Rockcraft"
+project = "12-Factor app support"
 author = "Canonical Ltd."
 
 
@@ -72,7 +72,7 @@
 # NOTE: The Open Graph Protocol (OGP) enhances page display in a social graph
 #       and is used by social media platforms; see https://ogp.me/
 
-ogp_site_url = "https://canonical-starter-pack.readthedocs-hosted.com/"
+ogp_site_url = ""
 
 
 # Preview name of the documentation website

docs/index.rst

@@ -4,49 +4,109 @@
 12-Factor app support in Charmcraft and Rockcraft
 =================================================
 
-**Coordinated pairs of Rockcraft and Charmcraft profiles designed to give you
-the content you need to generate rocks and charms for 12-Factor applications.**
-
-**A paragraph of one to three short sentences, that describe what the product
-does.** 
-
-**A third paragraph of similar length, this time explaining what need the
-product meets.**
-
-**Finally, a paragraph that describes whom the product is useful for.** 
-
----------
-
-In this documentation
----------------------
-
-..  grid:: 1 1 2 2
-
-   ..  grid-item:: :doc:`Tutorial <tutorial/index>`
-
-       **Start here**: a hands-on introduction to Example Product for new users
-
-   ..  grid-item:: :doc:`How-to guides <how-to/index>`
-
-      **Step-by-step guides** covering key operations and common tasks
-
-.. grid:: 1 1 2 2
-   :reverse:
-
-   .. grid-item:: :doc:`Reference </index>`
-
-      **Technical information** - specifications, APIs, architecture
-
-   .. grid-item:: :doc:`Explanation <explanation/index>`
-
-      **Discussion and clarification** of key topics
-
----------
+**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)
+
+The foundations: Juju, charms and rocks
+---------------------------------------
+
+The 12-factor charm 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
+  of applications at any scale and on any infrastructure.
+- A `charm <https://juju.is/docs/juju/charmed-operator>`_ is an operator -
+  business logic encapsulated in reusable software packages that automate every
+  aspect of an application's life.
+- `Charmcraft <https://canonical-charmcraft.readthedocs-hosted.com/en/stable/>`_
+  is a CLI tool that makes it easy and quick to initialize, package, and publish
+  charms.
+- `Rockcraft <https://documentation.ubuntu.com/rockcraft/en/latest/>`_ is a
+  tool to create rocks – a new generation of secure, stable and OCI-compliant
+  container images, based on Ubuntu.
+
+A Rockcraft framework (conceptually similar to a `snap
+extension <https://snapcraft.io/docs/snapcraft-extensions>`_) is initially
+used to facilitate the creation of a well structured, minimal and hardened
+container image, called a rock. A Charmcraft profile can then be leveraged to
+add a software operator (charm) around the aforementioned container image.
+
+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/>`_ 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
+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
 ---------------------
 
-The 12-Factor app project is a member of the Ubuntu family. It’s an open source
+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.
 
@@ -56,7 +116,7 @@ fixes and constructive feedback.
 * Contribute
 * Roadmap
 
-Thinking about using 12-Factor app rocks and charms in your next project? Get in touch!
+Thinking about using 12-Factor charms in your next project? Get in touch!
 
 
 .. toctree::