Documentation For Developers¶
Cloud Custodian makes every effort to provide comprehensive documentation. Any new features you add should be documented.
The documentation is built using sphinx.
The documentation is written using reStructured Text (
rst) and Markdown (
The sphinx documentation contains a useful introduction to
Find the Documentation¶
The root of the documentation is located in the
Within the documentation, topics are organized according to the following main areas:
In addition, the api documentation will be built from docstrings on classes and methods in source code.
rst files for these may be found in the
Edit the Documentation¶
In most cases, documentation edits will be made in docstrings on source code.
Docstrings should be written following the principles of pep 257.
rst directives allow for highlighting code examples:
class AutoTagUser(EventAction): """Tag a resource with the user who created/modified it. .. code-block:: yaml policies: - name: ec2-auto-tag-ownercontact resource: ec2 description: | Triggered when a new EC2 Instance is launched. Checks to see if it's missing the OwnerContact tag. If missing it gets created with the value of the ID of whomever called the RunInstances API mode: type: cloudtrail role: arn:aws:iam::123456789000:role/custodian-auto-tagger events: - RunInstances filters: - tag:OwnerContact: absent actions: - type: auto-tag-user tag: OwnerContact There's a number of caveats to usage. Resources which don't include tagging as part of their api may have some delay before automation kicks in to create a tag. Real world delay may be several minutes, with worst case into hours. This creates a race condition between auto tagging and automation. In practice this window is on the order of a fraction of a second, as we fetch the resource and evaluate the presence of the tag before attempting to tag it. References CloudTrail User https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html """
Render the Documentation¶
To build the documentation use the make target:
Builds are cached locally and incremental.
You can browse the locally built documentation by starting a web server in the build directory and navigating in a browser to http://localhost:8000
cd docs/build/html python -m http.server
Note the home page for cloudcustodian.io is built out of a separate repo. https://github.com/cloud-custodian/www.cloudcustodian.io