docs: split example page into example library (canonical#5645)

*What does it do?*
Create a single library of yaml examples. There are currently
examples in three places:
- the modules page
- doc/examples
- the yaml examples page

Here I collect ALL existing examples into a single "example library".
The yaml examples page is now a landing page/directory.

* Examples grouped (roughly) by operation or function.
* Standardised formatting across pages.
* Links to relevant module(s) included on all pages.
* Comments extracted from yaml files for better formatting.

Note: not all examples have descriptive titles or explanations
(yet). To be addressed in future work.

*Why is this done?*
* Improved module discoverability/usability for newer users.
* Streamlining.
  - We can now remove examples from the modules page, instead linking to
    relevant examples in the library. We can then remove tabs on the module
    page, to facilitate use of ctrl+f searching for long-time users.
  - We can remove the examples from `doc/examples`, so that examples are
    all in a single place.

doc/module-docs/cc_users_groups/example3.yaml

@@ -1,9 +1,4 @@
 #cloud-config
 users:
-- gecos: Big Stuff
-  groups: users, admin
-  lock_passwd: true
-  name: newsuper
+- name: newsuper
   shell: /bin/bash
-  ssh_import_id: ['lp:falcojr', 'gh:TheRealFalcon']
-  sudo: ALL=(ALL) NOPASSWD:ALL

doc/module-docs/cc_users_groups/example4.yaml

@@ -1,8 +1,5 @@
 #cloud-config
 users:
 - doas: [permit nopass newsuper, deny newsuper as root]
-  gecos: Big Stuff
-  groups: users, admin
-  lock_passwd: true
   name: newsuper
-  ssh_import_id: ['lp:falcojr', 'gh:TheRealFalcon']
+

doc/rtd/explanation/about-cloud-config.rst

@@ -0,0 +1,141 @@
+.. _about-cloud-config:
+
+About the cloud-config file
+***************************
+
+The ``#cloud-config`` file is a type of user data that cloud-init can consume
+to automatically set up various aspects of the system. It is commonly referred
+to as **cloud config**. Using cloud config to configure your machine leverages
+the best practices encoded into cloud-init's modules in a distribution-agnostic
+way.
+
+Note that networks are not configurable via the ``#cloud-config`` file because
+:ref:`network configuration <network_config>` comes from the cloud.
+
+How do I create a cloud-config file?
+====================================
+
+The cloud-config file uses `YAML version 1.1`_. The file is composed of a
+**header** and one or more **modules**.
+
+* **The header**:
+  The first line **must start** with ``#cloud-config``. This line identifies
+  the file to cloud-init and ensures that it will be processed as intended.
+
+* **The modules**:
+  After the header, every aspect of the system's configuration is controlled
+  through specific cloud-init modules.
+
+Most modules are specified through the use of one or more **top-level keys**,
+and the configuration options are set using YAML key-value pairs or list types,
+according to the config schema. It follows this general format:
+
+.. code-block:: yaml
+
+   #cloud-config
+   top-level-key:
+     config-key-1: config-value-1
+     config-key-2: config-value-2
+     list-type:
+     - list-value-1
+       additional-list-value-1
+     - list-value-2
+
+The order of the top-level keys is unimportant -- they can be written in any
+order, and cloud-init handles the order of operations.
+
+Let us consider a real example using the :ref:`Keyboard <mod_cc_keyboard>`
+module. The top-level key for this module is ``keyboard:``, and beneath that
+are the various configuration options for the module shown as key-value pairs:
+
+.. code-block:: yaml
+
+   #cloud-config
+   keyboard:
+     layout: us
+     model: pc105
+     variant: nodeadkeys
+     options: compose:rwin
+
+Not all modules require a top-level key, and will run on the system anyway if
+certain conditions are met. A full list of modules can be found
+:ref:`on our modules page <modules>`. This list also shows the valid schema for
+every module, and simple YAML examples.
+
+Checking your cloud-config file
+===============================
+
+Once you have constructed your cloud-config file, you can check it against
+the :ref:`cloud-config validation tool <check_user_data_cloud_config>`. This
+tool tests the YAML in your file against the cloud-init schema and will warn
+you of any errors.
+
+Example cloud-config file
+=========================
+
+The following code is an example of a complete user data cloud-config file.
+The :ref:`cloud-config example library <yaml_examples>` contains further
+examples that can be copy/pasted and adapted to your needs.
+
+.. code-block:: yaml
+
+   #cloud-config
+
+   # Basic system setup
+   hostname: example-host
+   fqdn: example-host.example.com
+
+   # User setup configuration
+   users:
+     - name: exampleuser
+       gecos: Example User
+       sudo: ['ALL=(ALL) NOPASSWD:ALL']
+       groups: sudo
+       homedir: /home/exampleuser
+       shell: /bin/bash
+       ssh_authorized_keys:
+         - ssh-rsa AAAAB3...restofpublickey user@host
+
+   # Change passwords for exampleuser using chpasswd
+   chpasswd:
+     expire: false
+     users:
+     - {name: exampleuser, password: terriblepassword12345, type: text}
+
+   # Package management
+   package_update: true
+   package_upgrade: true
+   packages:
+     - git
+     - nginx
+     - python3
+
+   # Commands to run at the end of the cloud-init process
+   runcmd:
+     - echo "Hello, world!" > /etc/motd
+     - systemctl restart nginx
+     - mkdir -p /var/www/html
+     - echo "<html><body><h1>Welcome to the party, pal!</h1></body></html>" > /var/www/html/index.html
+
+   # Write files to the instance
+   write_files:
+     - path: /etc/example_config.conf
+       content: |
+         [example-config]
+         key=value
+     - path: /etc/motd
+       content: |
+         Some text that will appear in your MOTD!
+
+   # Final message, shown after cloud-init completes
+   final_message: "The system is up, after $UPTIME seconds"
+
+   # Reboot the instance after configuration
+   power_state:
+     mode: reboot
+     message: Rebooting after initial setup
+     timeout: 30
+     condition: True
+
+.. LINKS
+.. _YAML version 1.1: https://yaml.org/spec/1.1/current.html

doc/rtd/explanation/index.rst

@@ -12,6 +12,7 @@ knowledge and become better at using and configuring ``cloud-init``.
 
    introduction.rst
    format.rst
+   about-cloud-config.rst
    configuration.rst
    boot.rst
    first_boot.rst

doc/rtd/reference/examples.rst

@@ -1,7 +1,12 @@
 .. _yaml_examples:
 
-Cloud config examples
-*********************
+All cloud config examples
+*************************
+
+.. note::
+   This page is a summary containing all the cloud config YAML examples
+   together. If you would like to explore examples by operation or process
+   instead, refer to the :ref:`examples library <examples_library>`.
 
 Including users and groups
 ==========================
@@ -150,3 +155,4 @@ Create partitions and filesystems
 .. _chef: http://www.chef.io/chef/
 .. _puppet: http://puppetlabs.com/
 .. _ansible: https://docs.ansible.com/ansible/latest/
+

doc/rtd/reference/examples_library.rst

@@ -0,0 +1,59 @@
+.. _examples_library:
+
+Cloud config examples library
+*****************************
+
+.. note::
+   This page is an index to all the cloud config YAML examples, organised by
+   operation or process. If you prefer to use a single-page summary containing
+   every cloud config yaml example, refer to the
+   :ref:`all examples page <yaml_examples>`.
+
+.. include:: yaml_examples/index_boot.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_security.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_fs.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_users.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_hostname.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_network.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_packages.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_logging.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_config_manager.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_distro.rst
+   :end-before: .. TOC
+
+.. include:: yaml_examples/index_misc.rst
+   :end-before: .. TOC
+
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    yaml_examples/index_boot
+    yaml_examples/index_security
+    yaml_examples/index_fs
+    yaml_examples/index_users
+    yaml_examples/index_hostname
+    yaml_examples/index_network
+    yaml_examples/index_packages
+    yaml_examples/index_logging
+    yaml_examples/index_config_manager
+    yaml_examples/index_distro
+    yaml_examples/index_misc

doc/rtd/reference/index.rst

@@ -12,6 +12,7 @@ matrices and so on.
 
    modules.rst
    examples.rst
+   examples_library.rst
    cli.rst
    availability.rst
    faq.rst

doc/rtd/reference/yaml_examples/ansible.rst

@@ -0,0 +1,54 @@
+.. _cce-ansible:
+
+Install Ansible
+***************
+
+These examples show how to achieve a basic installation of Ansible, and
+configures the location that playbooks should be pulled from.
+
+For a full list of keys, refer to the :ref:`Ansible module <mod_cc_ansible>`
+schema.
+
+Install via package manager
+===========================
+
+This example will use the operating system distribution's package manager to
+install Ansible.
+
+.. literalinclude:: ../../../module-docs/cc_ansible/example1.yaml
+   :language: yaml
+   :linenos:
+
+Install via pip
+===============
+
+This example uses the Python package manager ``pip`` to install Ansible.
+
+.. literalinclude:: ../../../module-docs/cc_ansible/example2.yaml
+   :language: yaml
+   :linenos:
+
+Install and run Ansible pull
+============================
+
+If you're already installing other packages, you may want to manually install
+Ansible to avoid multiple calls to your package manager. This example shows
+how to install Ansible using ``pip`` and run the ``ubuntu.yml`` playbook,
+pulled from a specific git repository.
+
+For a full list of keys, refer to the :ref:`Ansible module <mod_cc_ansible>`
+schema.
+
+.. code-block:: yaml
+
+    #cloud-config
+    package_update: true
+    package_upgrade: true
+    packages:
+      - git
+    ansible:
+      install_method: pip
+      pull:
+        url: "https://github.com/holmanb/vmboot.git"
+        playbook_name: ubuntu.yml
+