API documentation

[boompig]

Is there any documentation outside the source code? Read the docs doesn't have any useful information.

[phobologic]

Largely there isn't a ton of documentation since we try to keep troposphere a one to one copy of the cloudformation templating language, so you can usually just use that to describe what fields/attributes various resources/properties have.

What kind of documentation would you like to see though?

[boompig]

Auto-generated documentation of methods and classes would be nice. Sphinx is a good tool for this.

[phobologic]

Yeah - the classes themselves are pretty bare of docs, unfortunately. It'd just be signatures.

that said I know @markpeek is working occasionally on integrating the Cloudformation schema that comes directly from AWS, and that has links to the actual cloudformation docs for each resource, so maybe we could do something cool with that at some point.

Anyway, thanks for the clarification.

[ScriptAutomate]

I recently was thinking about this problem with Troposphere, and saw that this issue was opened a few years ago. It's still an existing problem, and I thought I'd add some thoughts here in case others wanted to contribute.

Some initial Sphinx documentation has been slowly added since this issue discussion ended, with #1311 and #1314, but Classes are pretty much just as-is (source code).

I would love to help with this, actually, but may need some help. I'm thinking something like the following could be used to automate and expand the documentation with Sphinx and the CFN resource spec documentation links:

To Start

Some priority items:

• Travis CI should be re-compiling via Sphinx with Troposphere readthedocs integration always using the latest compiled release version. It's currently only reflecting when Sphinx was initially added to this repo back with v2.4.1
  • This would need to also involve release in ./docs/conf.py updating to the current version each time a new Troposphere release occurs
• Basic directions/documentation added for how to run Sphinx, and contribute to the documentation (compiling with Python 2.7, what make commands are used like make html? etc.)

Furthering Automated API Documentation Ideas

• See if there is a way to run Sphinx to compile without needing to use Python 2.7.x to do so, as currently it fails due to hangups around basestring when it runs in Python 3.6+. With 2.7 being EOL, would be good to get Sphinx compiling in Python3
• Add sphinx.ext.napolean to the extensions list in ./docs/conf.py so that documentation can be done with Google Style Docstrings, for better readability
• Make use of the GitHub documentation "source" for the CFN user guide doc endpoints which is as close to a one-to-one of their live documentation as you'll get without getting stuck making a ton of webscraping calls
  • From here, the CFN resource spec files should point to proper docs files where MarkDown can be parsed for insertion into Troposphere classes

Example

AWS::EC2::DHCPOptions

• Documentation points to https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-dhcp-options.html from the CFN resource spec.
  • Equivalent location in the GitHub repo: https://github.com/awsdocs/aws-cloudformation-user-guide/blob/master/doc_source/aws-resource-ec2-dhcp-options.md

It would just be a matter of flipping aws-resource-ec2-dhcp-options.html to aws-resource-ec2-dhcp-options.md for the most part.

NOTE: There are errors/exceptions with this, which I am tracking in my AWS CFN resource spec auditor repository via documentation-lookup-errors.json. This repository may be of help, in general, when it comes to this process.

A proof-of-concept for potential docstring format in a class, using AWS::EC2::CustomerGateway and AWS::EC2::DHCPOptions:

./troposphere/ec2.py

...
...
class CustomerGateway(AWSObject):
    """Specifies a customer gateway.

    Attributes:
        BgpAsn (integer): For devices that support BGP, the customer gateway's BGP ASN.
        IpAddress (basestring): The Internet-routable IP address for the customer gateway's outside interface. The address must be static.
        Tags (list(troposphere.Tags), optional): One or more tags for the customer gateway.
        Type (basestring): The type of VPN connection that this customer gateway supports (ipsec.1).

    """
    resource_type = "AWS::EC2::CustomerGateway"

    props = {
        'BgpAsn': (integer, True),
        'IpAddress': (basestring, True),
        'Tags': ((Tags, list), False),
        'Type': (basestring, True),
    }


class DHCPOptions(AWSObject):
    """Specifies a set of DHCP options for your VPC.

    You must specify at least one of the following properties: DomainNameServers, NetbiosNameServers, NtpServers. If you specify NetbiosNameServers, you must specify NetbiosNodeType.
    
    Attributes:
        DomainName (basestring, optional): This value is used to complete unqualified DNS hostnames. If you're using AmazonProvidedDNS in us-east-1, specify ec2.internal. If you're using AmazonProvidedDNS in another Region, specify region.compute.internal (for example, ap-northeast-1.compute.internal). Otherwise, specify a domain name (for example, MyCompany.com).
        DomainNameServers (list, optional): The IPv4 addresses of up to four domain name servers, or AmazonProvidedDNS. The default DHCP option set specifies AmazonProvidedDNS. If specifying more than one domain name server, specify the IP addresses in a single parameter, separated by commas. To have your instance to receive a custom DNS hostname as specified in DomainName, you must set this to a custom DNS server.
        NetbiosNameServers (list, optional): The IPv4 addresses of up to four NetBIOS name servers.
        NetbiosNodeType (integer, optional): The NetBIOS node type (1, 2, 4, or 8). We recommend that you specify 2 (broadcast and multicast are not currently supported).
        NtpServers (list, optional): The IPv4 addresses of up to four Network Time Protocol (NTP) servers.
        Tags (list(troposphere.Tags), optional): Any tags assigned to the DHCP options set.

    """
    resource_type = "AWS::EC2::DHCPOptions"

    props = {
        'DomainName': (basestring, False),
        'DomainNameServers': (list, False),
        'NetbiosNameServers': (list, False),
        'NetbiosNodeType': (integer, False),
        'NtpServers': (list, False),
        'Tags': ((Tags, list), False),
    }
...
...

This renders well in readthedocs when using the sphinx.ext.napolean Sphinx extension, and those two examples are taking information directly found within the CFN docs. I've helped do something similar for a PowerShell-based module used for CFN development, ultimately injecting help documentation directly into the source code:

• VaporShell/Issue/Feature Request: Expand Comment-Based Help Content of ResourceType and PropertyType Functions

I'm wondering whether @markpeek, @lowcloudnine, and/or others could provide their input? And if I could be of help in the process? I've only begun poking around with Sphinx and its use here, and I wanted to document my thoughts in this issue while it's on my mind.

[lsh-0]

+1 for this

readthedocs is pulling in a badge with the current troposphere version, when in reality those docs haven't been updated since 2.4.3 in (Feb?) 2019:

[markpeek]

@lsh-0 thank you for letting me know about the docs. I just pushed some changes so "latest" is up to date and "stable" docs should build upon the next release.