SET-1468: Add documentation for OpenStack tools

Closes: https://warthogs.atlassian.net/browse/SET-1468
Signed-off-by: Nicolas Bock <nicolas.bock@canonical.com>

Author: nicolasbock

docs/.custom_wordlist.txt

@@ -1,8 +1,10 @@
 # Leave a blank line at the end of this file to support concatenation
 apache
 AthenaV2
+az
 backend
 backends
+balancers
 Caracal
 ceph
 Charmcraft
@@ -12,9 +14,11 @@ config
 configs
 cryptographically
 DHSS
+distributable
 dvipng
 fonts
 freefont
+functest
 github
 GPG
 gyre
@@ -25,6 +29,7 @@ IDP
 IDPs
 Intersphinx
 io
+ipv
 JDK
 Jira
 Kanban
@@ -33,16 +38,20 @@ Keycloak
 lang
 LaTeX
 latexmk
+lnav
 manila
 Manila
+microceph
 Multipass
 neutronclient
+octavia
 oidc
 openidc
 OpenIDC
 openstack
 openstackclient
 openstackclients
+OSCI
 otf
 plantuml
 PNG
@@ -52,10 +61,14 @@ Pygments
 QEMU
 readthedocs
 Rockcraft
+routable
 rst
 rsync
+samltestid
+sg
 sitemapindex
 sos
+ssl
 SSL
 stsstack
 STSStack
@@ -73,6 +86,8 @@ uncommenting
 URIs
 url
 utils
+vips
+vm
 VMs
 WCAG
 webhook

docs/conf.py

@@ -251,6 +251,7 @@
 
 # myst_enable_extensions = set()
 
+# myst_heading_anchors = 3
 
 # Custom Sphinx extensions; see
 # https://www.sphinx-doc.org/en/master/usage/extensions/index.html

docs/index.rst

@@ -3,17 +3,17 @@ STSStack-Bundles Documentation
 
 STSStack-Bundles is a set of bundles that leverage Juju bundle overlays to allow generating complex deployments from a number of options using a single command. These bundles are designed for use with the Juju OpenStack provider.
 
-The top level directory contains a set of modules, each of which has a generate-bundle.sh script which you can use to create a deployment from a number of options.
+The top level directory contains a set of modules, each of which has a ``generate-bundle.sh`` script which you can use to create a deployment from a number of options.
 
-NOTE: see generate-bundle.sh --help for option info about using that particular module.
+NOTE: see :doc:`user-docs/generate-bundle` ``--help`` for option info about using that particular module.
 
 Basic usage:
 
- * give your deployment a name with (--name)
+ * give your deployment a name with (``--name``)
  * create a Juju model using the given name or use existing one
- * add one or more feature overlays depending on what you need (see --list-overlays)
- * resources are stored under a named directory so as to be able to avoid collisions and replay later (--replay)
- * immediate deploy (--run) or save for later
+ * add one or more feature overlays depending on what you need (see ``--list-overlays``)
+ * resources are stored under a named directory so as to be able to avoid collisions and replay later (``--replay``)
+ * immediate deploy (``--run``) or save for later
 
 
 .. toctree::
@@ -39,4 +39,3 @@ In this documentation
       :link-type: doc
 
       **For contributors** - how to contribute to STSStack-Bundles.
-

docs/user-docs/generate-bundle.rst

@@ -0,0 +1,29 @@
+generate-bundle.sh
+==================
+
+The `generate-bundle.sh` script is used to create a bundle, and optionally deploy it, of a Charmed OpenStack, Kubernetes, or Ceph deployment.
+
+Usage
+-----
+
+Run the script from the project root:
+
+.. code::
+
+    ./generate-bundle.sh
+
+This will generate the necessary files for deployment in the `b` directory.
+
+Options
+-------
+
+You can pass additional options to customise the build process. For example:
+
+.. code::
+
+    ./generate-bundle.sh --keystone-ha --num-compute 2 --run
+
+Prerequisites
+-------------
+
+Make sure you have all required dependencies installed before running the script.

docs/user-docs/index.rst

@@ -6,6 +6,7 @@ User Documentation
    :maxdepth: 2
 
    usage
+   generate-bundle.sh<generate-bundle>
    openstack/index
    ceph/index
    osm/index

docs/user-docs/openstack/index.md

@@ -15,6 +15,7 @@ OVN <ovn>
 SAML <saml>
 Keystone + OpenIDC <keystone-openidc>
 Manila <manila-generic>
+Tools <tools>
 ```
 
 ````{grid} 1 1 2 2
@@ -89,4 +90,9 @@ Dynamic Routing
 :link-type: doc
 **Tutorial** - learn how to deploy an OpenStack cloud on `serverstack`
 ```
+```{grid-item-card} Tools
+:link: tools
+:link-type: doc
+**Tools** - OpenStack Tools
+```
 ````