From 1071b9940b4e114cd2eabf290b739f92fbab33de Mon Sep 17 00:00:00 2001
From: Wesley Wiedenmeier <wesley.wiedenmeier@gmail.com>
Date: Sun, 28 Aug 2016 17:56:17 -0500
Subject: Improve module documentation and doc cleanup.
This adds lots of config module documentation in a standard format.
It will greatly improve the content at readthedocs.
Additionally:
* Add a 'doc' env to tox.ini
* Changed default highlight language for sphinx conf from python to yaml
most examples in documentation are yaml configs
* Updated datasource examples to highlight sh code properly
---
doc/rtd/conf.py | 2 +-
doc/rtd/topics/datasources.rst | 48 +++----
doc/rtd/topics/dir_layout.rst | 4 +-
doc/rtd/topics/examples.rst | 52 +++++---
doc/rtd/topics/format.rst | 12 +-
doc/rtd/topics/modules.rst | 297 +----------------------------------------
doc/rtd/topics/moreinfo.rst | 6 +-
7 files changed, 78 insertions(+), 343 deletions(-)
(limited to 'doc/rtd')
diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index 8a391f21..66b3b654 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -48,7 +48,7 @@ version = version.version_string()
release = version
# Set the default Pygments syntax
-highlight_language = 'python'
+highlight_language = 'yaml'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst
index 0d7d4aca..3a9c808c 100644
--- a/doc/rtd/topics/datasources.rst
+++ b/doc/rtd/topics/datasources.rst
@@ -1,11 +1,11 @@
.. _datasources:
-=========
+===========
Datasources
-=========
-----------
+===========
+----------------------
What is a datasource?
-----------
+----------------------
Datasources are sources of configuration data for cloud-init that typically come
from the user (aka userdata) or come from the stack that created the configuration
@@ -70,9 +70,9 @@ The current interface that a datasource object must provide is the following:
def get_package_mirror_info(self)
----------------------------
+---
EC2
----------------------------
+---
The EC2 datasource is the oldest and most widely used datasource that cloud-init
supports. This datasource interacts with a *magic* ip that is provided to the
@@ -130,61 +130,61 @@ To see which versions are supported from your cloud provider use the following U
...
latest
----------------------------
+------------
Config Drive
----------------------------
+------------
.. include:: ../../sources/configdrive/README.rst
----------------------------
+----------
OpenNebula
----------------------------
+----------
.. include:: ../../sources/opennebula/README.rst
----------------------------
+---------
Alt cloud
----------------------------
+---------
.. include:: ../../sources/altcloud/README.rst
----------------------------
+--------
No cloud
----------------------------
+--------
.. include:: ../../sources/nocloud/README.rst
----------------------------
+----
MAAS
----------------------------
+----
*TODO*
For now see: http://maas.ubuntu.com/
----------------------------
+----------
CloudStack
----------------------------
+----------
.. include:: ../../sources/cloudstack/README.rst
----------------------------
+---
OVF
----------------------------
+---
*TODO*
For now see: https://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/files/head:/doc/sources/ovf/
----------------------------
+---------
OpenStack
----------------------------
+---------
.. include:: ../../sources/openstack/README.rst
----------------------------
+-------------
Fallback/None
----------------------------
+-------------
This is the fallback datasource when no other datasource can be selected. It is
the equivalent of a *empty* datasource in that it provides a empty string as userdata
diff --git a/doc/rtd/topics/dir_layout.rst b/doc/rtd/topics/dir_layout.rst
index 8815d33d..6dcb22ce 100644
--- a/doc/rtd/topics/dir_layout.rst
+++ b/doc/rtd/topics/dir_layout.rst
@@ -1,6 +1,6 @@
-=========
+================
Directory layout
-=========
+================
Cloudinits's directory structure is somewhat different from a regular application::
diff --git a/doc/rtd/topics/examples.rst b/doc/rtd/topics/examples.rst
index 36508bde..2e6cfa1e 100644
--- a/doc/rtd/topics/examples.rst
+++ b/doc/rtd/topics/examples.rst
@@ -1,11 +1,11 @@
.. _yaml_examples:
-=========
+=====================
Cloud config examples
-=========
+=====================
Including users and groups
----------------------------
+--------------------------
.. literalinclude:: ../../examples/cloud-config-user-groups.txt
:language: yaml
@@ -21,21 +21,21 @@ Writing out arbitrary files
Adding a yum repository
----------------------------
+-----------------------
.. literalinclude:: ../../examples/cloud-config-yum-repo.txt
:language: yaml
:linenos:
Configure an instances trusted CA certificates
-------------------------------------------------------
+----------------------------------------------
.. literalinclude:: ../../examples/cloud-config-ca-certs.txt
:language: yaml
:linenos:
Configure an instances resolv.conf
-------------------------------------------------------
+----------------------------------
*Note:* when using a config drive and a RHEL like system resolv.conf
will also be managed 'automatically' due to the available information
@@ -47,28 +47,28 @@ that wish to have different settings use this module.
:linenos:
Install and run `chef`_ recipes
-------------------------------------------------------
+-------------------------------
.. literalinclude:: ../../examples/cloud-config-chef.txt
:language: yaml
:linenos:
Setup and run `puppet`_
-------------------------------------------------------
+-----------------------
.. literalinclude:: ../../examples/cloud-config-puppet.txt
:language: yaml
:linenos:
Add apt repositories
----------------------------
+--------------------
.. literalinclude:: ../../examples/cloud-config-add-apt-repos.txt
:language: yaml
:linenos:
Run commands on first boot
----------------------------
+--------------------------
.. literalinclude:: ../../examples/cloud-config-boot-cmds.txt
:language: yaml
@@ -80,21 +80,21 @@ Run commands on first boot
Alter the completion message
----------------------------
+----------------------------
.. literalinclude:: ../../examples/cloud-config-final-message.txt
:language: yaml
:linenos:
Install arbitrary packages
----------------------------
+--------------------------
.. literalinclude:: ../../examples/cloud-config-install-packages.txt
:language: yaml
:linenos:
Run apt or yum upgrade
----------------------------
+----------------------
.. literalinclude:: ../../examples/cloud-config-update-packages.txt
:language: yaml
@@ -108,26 +108,46 @@ Adjust mount points mounted
:linenos:
Call a url when finished
----------------------------
+------------------------
.. literalinclude:: ../../examples/cloud-config-phone-home.txt
:language: yaml
:linenos:
Reboot/poweroff when finished
----------------------------
+-----------------------------
.. literalinclude:: ../../examples/cloud-config-power-state.txt
:language: yaml
:linenos:
Configure instances ssh-keys
----------------------------
+----------------------------
.. literalinclude:: ../../examples/cloud-config-ssh-keys.txt
:language: yaml
:linenos:
+Additional apt configuration
+----------------------------
+
+.. literalinclude:: ../../examples/cloud-config-apt.txt
+ :language: yaml
+ :linenos:
+
+Disk setup
+----------
+
+.. literalinclude:: ../../examples/cloud-config-disk-setup.txt
+ :language: yaml
+ :linenos:
+
+Register RedHat Subscription
+----------------------------
+
+.. literalinclude:: ../../examples/cloud-config-rh_subscription.txt
+ :language: yaml
+ :linenos:
.. _chef: http://www.opscode.com/chef/
.. _puppet: http://puppetlabs.com/
diff --git a/doc/rtd/topics/format.rst b/doc/rtd/topics/format.rst
index eba9533f..1dd92309 100644
--- a/doc/rtd/topics/format.rst
+++ b/doc/rtd/topics/format.rst
@@ -1,18 +1,18 @@
-=========
+=======
Formats
-=========
+=======
User data that will be acted upon by cloud-init must be in one of the following types.
Gzip Compressed Content
-------------------------
+-----------------------
Content found to be gzip compressed will be uncompressed.
The uncompressed data will then be used as if it were not compressed.
This is typically is useful because user-data is limited to ~16384 [#]_ bytes.
Mime Multi Part Archive
-------------------------
+-----------------------
This list of rules is applied to each part of this multi-part file.
Using a mime-multi part file, the user can specify more than one type of data.
@@ -31,7 +31,7 @@ Supported content-types:
- text/cloud-boothook
Helper script to generate mime messages
-~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python
@@ -59,7 +59,7 @@ Helper script to generate mime messages
User-Data Script
-------------------------
+----------------
Typically used by those who just want to execute a shell script.
diff --git a/doc/rtd/topics/modules.rst b/doc/rtd/topics/modules.rst
index 4202338b..57892f2d 100644
--- a/doc/rtd/topics/modules.rst
+++ b/doc/rtd/topics/modules.rst
@@ -1,342 +1,57 @@
=======
Modules
=======
-
-Apt Configure
--------------
-
-**Internal name:** ``cc_apt_configure``
-
.. automodule:: cloudinit.config.cc_apt_configure
-
-Apt Pipelining
---------------
-
-**Internal name:** ``cc_apt_pipelining``
-
.. automodule:: cloudinit.config.cc_apt_pipelining
-
-Bootcmd
--------
-
-**Internal name:** ``cc_bootcmd``
-
.. automodule:: cloudinit.config.cc_bootcmd
-
-Byobu
------
-
-**Internal name:** ``cc_byobu``
-
.. automodule:: cloudinit.config.cc_byobu
-
-Ca Certs
---------
-
-**Internal name:** ``cc_ca_certs``
-
.. automodule:: cloudinit.config.cc_ca_certs
-
-Chef
-----
-
-**Internal name:** ``cc_chef``
-
.. automodule:: cloudinit.config.cc_chef
- :members:
-
-Debug
------
-
-**Internal name:** ``cc_debug``
-
.. automodule:: cloudinit.config.cc_debug
- :members:
-
-Disable Ec2 Metadata
---------------------
-
-**Internal name:** ``cc_disable_ec2_metadata``
-
.. automodule:: cloudinit.config.cc_disable_ec2_metadata
-
-Disk Setup
-----------
-
-**Internal name:** ``cc_disk_setup``
-
.. automodule:: cloudinit.config.cc_disk_setup
-
-Emit Upstart
-------------
-
-**Internal name:** ``cc_emit_upstart``
-
.. automodule:: cloudinit.config.cc_emit_upstart
-
-Final Message
--------------
-
-**Internal name:** ``cc_final_message``
-
+.. automodule:: cloudinit.config.cc_fan
.. automodule:: cloudinit.config.cc_final_message
-
-Foo
----
-
-**Internal name:** ``cc_foo``
-
.. automodule:: cloudinit.config.cc_foo
-
-Growpart
---------
-
-**Internal name:** ``cc_growpart``
-
.. automodule:: cloudinit.config.cc_growpart
-
-Grub Dpkg
----------
-
-**Internal name:** ``cc_grub_dpkg``
-
.. automodule:: cloudinit.config.cc_grub_dpkg
-
-Keys To Console
----------------
-
-**Internal name:** ``cc_keys_to_console``
-
.. automodule:: cloudinit.config.cc_keys_to_console
-
-Landscape
----------
-
-**Internal name:** ``cc_landscape``
-
.. automodule:: cloudinit.config.cc_landscape
-
-Locale
-------
-
-**Internal name:** ``cc_locale``
-
.. automodule:: cloudinit.config.cc_locale
-
-Mcollective
------------
-
-**Internal name:** ``cc_mcollective``
-
+.. automodule:: cloudinit.config.cc_lxd
.. automodule:: cloudinit.config.cc_mcollective
-
-Migrator
---------
-
-**Internal name:** ``cc_migrator``
-
.. automodule:: cloudinit.config.cc_migrator
-
-Mounts
-------
-
-**Internal name:** ``cc_mounts``
-
.. automodule:: cloudinit.config.cc_mounts
-
-Package Update Upgrade Install
-------------------------------
-
-**Internal name:** ``cc_package_update_upgrade_install``
-
+.. automodule:: cloudinit.config.cc_ntp
.. automodule:: cloudinit.config.cc_package_update_upgrade_install
-
-Phone Home
-----------
-
-**Internal name:** ``cc_phone_home``
-
.. automodule:: cloudinit.config.cc_phone_home
-
-Power State Change
-------------------
-
-**Internal name:** ``cc_power_state_change``
-
.. automodule:: cloudinit.config.cc_power_state_change
-
-Puppet
-------
-
-**Internal name:** ``cc_puppet``
-
.. automodule:: cloudinit.config.cc_puppet
-
-Resizefs
---------
-
-**Internal name:** ``cc_resizefs``
-
.. automodule:: cloudinit.config.cc_resizefs
-
-Resolv Conf
------------
-
-**Internal name:** ``cc_resolv_conf``
-
.. automodule:: cloudinit.config.cc_resolv_conf
-
-Rightscale Userdata
--------------------
-
-**Internal name:** ``cc_rightscale_userdata``
-
+.. automodule:: cloudinit.config.cc_rh_subscription
.. automodule:: cloudinit.config.cc_rightscale_userdata
-
-Rsyslog
--------
-
-**Internal name:** ``cc_rsyslog``
-
.. automodule:: cloudinit.config.cc_rsyslog
-
-Runcmd
-------
-
-**Internal name:** ``cc_runcmd``
-
.. automodule:: cloudinit.config.cc_runcmd
-
-Salt Minion
------------
-
-**Internal name:** ``cc_salt_minion``
-
.. automodule:: cloudinit.config.cc_salt_minion
-
-Scripts Per Boot
-----------------
-
-**Internal name:** ``cc_scripts_per_boot``
-
.. automodule:: cloudinit.config.cc_scripts_per_boot
-
-Scripts Per Instance
---------------------
-
-**Internal name:** ``cc_scripts_per_instance``
-
.. automodule:: cloudinit.config.cc_scripts_per_instance
-
-Scripts Per Once
-----------------
-
-**Internal name:** ``cc_scripts_per_once``
-
.. automodule:: cloudinit.config.cc_scripts_per_once
-
-Scripts User
-------------
-
-**Internal name:** ``cc_scripts_user``
-
.. automodule:: cloudinit.config.cc_scripts_user
-
-Scripts Vendor
---------------
-
-**Internal name:** ``cc_scripts_vendor``
-
.. automodule:: cloudinit.config.cc_scripts_vendor
-
-Seed Random
------------
-
-**Internal name:** ``cc_seed_random``
-
.. automodule:: cloudinit.config.cc_seed_random
-
-Set Hostname
-------------
-
-**Internal name:** ``cc_set_hostname``
-
.. automodule:: cloudinit.config.cc_set_hostname
-
-Set Passwords
--------------
-
-**Internal name:** ``cc_set_passwords``
-
.. automodule:: cloudinit.config.cc_set_passwords
-
-Ssh
----
-
-**Internal name:** ``cc_ssh``
-
+.. automodule:: cloudinit.config.cc_snappy
+.. automodule:: cloudinit.config.cc_spacewalk
.. automodule:: cloudinit.config.cc_ssh
-
-Ssh Authkey Fingerprints
-------------------------
-
-**Internal name:** ``cc_ssh_authkey_fingerprints``
-
.. automodule:: cloudinit.config.cc_ssh_authkey_fingerprints
-
-Ssh Import Id
--------------
-
-**Internal name:** ``cc_ssh_import_id``
-
.. automodule:: cloudinit.config.cc_ssh_import_id
-
-Timezone
---------
-
-**Internal name:** ``cc_timezone``
-
.. automodule:: cloudinit.config.cc_timezone
-
-Ubuntu Init Switch
-------------------
-
-**Internal name:** ``cc_ubuntu_init_switch``
-
.. automodule:: cloudinit.config.cc_ubuntu_init_switch
- :members:
-
-Update Etc Hosts
-----------------
-
-**Internal name:** ``cc_update_etc_hosts``
-
.. automodule:: cloudinit.config.cc_update_etc_hosts
-
-Update Hostname
----------------
-
-**Internal name:** ``cc_update_hostname``
-
.. automodule:: cloudinit.config.cc_update_hostname
-
-Users Groups
-------------
-
-**Internal name:** ``cc_users_groups``
-
.. automodule:: cloudinit.config.cc_users_groups
-
-Write Files
------------
-
-**Internal name:** ``cc_write_files``
-
.. automodule:: cloudinit.config.cc_write_files
-
-Yum Add Repo
-------------
-
-**Internal name:** ``cc_yum_add_repo``
-
.. automodule:: cloudinit.config.cc_yum_add_repo
diff --git a/doc/rtd/topics/moreinfo.rst b/doc/rtd/topics/moreinfo.rst
index 19e96af0..b34cb7dc 100644
--- a/doc/rtd/topics/moreinfo.rst
+++ b/doc/rtd/topics/moreinfo.rst
@@ -1,9 +1,9 @@
-=========
+================
More information
-=========
+================
Useful external references
--------------------------
+--------------------------
- `The beauty of cloudinit`_
- `Introduction to cloud-init`_ (video)
--
cgit v1.2.3