Add docs (#43)

* add_docs: add code of conduct

* add_docs: mkdocs config

* add_docs: add custom docs command in makefile

* add_docs: update requirements

* add_docs: folder

* add_docs: add docs strings

* add_docs: add docs requirements

* add_docs: add read the docs yml

* add_docs: update dependencies

* add_docs: update docs requirements

* add_docs: add docs badge to readme

* add_docs: fix makefile

* add_docs: update requirements inside the read the docs

* add_docs: more docs

* add_docs: restore function

* add_docs: more docs

* Apply suggestions from code review

Co-Authored-By: Oliver Crawford <[email protected]>

* Update pycfmodel/model/resources/properties/policy_document.py

Co-Authored-By: Oliver Crawford <[email protected]>

* add_docs: more docs

Co-authored-by: Oliver Crawford <[email protected]>

.readthedocs.yml

@@ -0,0 +1,15 @@
+version: 2
+
+mkdocs:
+  configuration: mkdocs.yml
+
+formats: all
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
+        - docs

CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behaviour that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behaviour by participants include:
+
+* The use of sexualized language or imagery and sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behaviour and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behaviour.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviours that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported by contacting the project team at [email protected]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+

Makefile

@@ -6,6 +6,9 @@ install:
 install-dev: install
 	pip install -e ".[dev]"
 
+install-docs:
+	pip install -e ".[dev,docs]"
+
 format:
 	black .
 
@@ -24,6 +27,9 @@ coverage:
 test: lint component
 
 freeze:
-	PIP_CONFIG_FILE=pip.conf pip-compile --no-index --output-file requirements.txt setup.py
+	CUSTOM_COMPILE_COMMAND="make freeze" PIP_CONFIG_FILE=pip.conf pip-compile --no-index --output-file requirements.txt setup.py
+
+freeze-upgrade:
+	CUSTOM_COMPILE_COMMAND="make freeze-upgrade" pip-compile --no-index --upgrade --output-file requirements.txt setup.py
 
-.PHONY: install install-dev lint component coverage test freeze format
+.PHONY: install install-dev install-docs lint component coverage test freeze freeze-upgrade format

README.md

@@ -4,6 +4,7 @@
 [![PyPI version](https://badge.fury.io/py/pycfmodel.svg)](https://badge.fury.io/py/pycfmodel)
 [![Total alerts](https://img.shields.io/lgtm/alerts/g/Skyscanner/pycfmodel.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/Skyscanner/pycfmodel/alerts/)
 [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/Skyscanner/pycfmodel.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/Skyscanner/pycfmodel/context:python)
+[![Documentation Status](https://readthedocs.org/projects/pycfmodel/badge/?version=latest)](https://pycfmodel.readthedocs.io/en/latest/?badge=latest)
 
 *A python model for Cloud Formation scripts.*
 

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/code_of_conduct.md

@@ -0,0 +1 @@
+../CODE_OF_CONDUCT.md

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/reference/cfmodel.md

@@ -0,0 +1,3 @@
+::: pycfmodel.model.cf_model
+
+::: pycfmodel.model.parameter

docs/reference/properties.md

@@ -0,0 +1,11 @@
+::: pycfmodel.model.resources.properties.property
+
+::: pycfmodel.model.resources.properties.policy
+
+::: pycfmodel.model.resources.properties.policy_document
+
+::: pycfmodel.model.resources.properties.security_group_egress_prop
+
+::: pycfmodel.model.resources.properties.security_group_ingress_prop
+
+::: pycfmodel.model.resources.properties.statement

docs/reference/resources.md

@@ -0,0 +1,28 @@
+::: pycfmodel.model.resources.generic_resource
+
+::: pycfmodel.model.resources.iam_group
+
+::: pycfmodel.model.resources.iam_managed_policy
+
+::: pycfmodel.model.resources.iam_policy
+
+::: pycfmodel.model.resources.iam_role
+
+::: pycfmodel.model.resources.iam_user
+
+::: pycfmodel.model.resources.kms_key
+
+::: pycfmodel.model.resources.resource
+
+::: pycfmodel.model.resources.s3_bucket_policy
+
+::: pycfmodel.model.resources.security_group
+
+::: pycfmodel.model.resources.security_group_egress
+
+::: pycfmodel.model.resources.security_group_ingress
+
+::: pycfmodel.model.resources.sns_topic_policy
+
+::: pycfmodel.model.resources.sqs_queue_policy
+

docs/stylesheets/extra.css

@@ -0,0 +1,38 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+  margin-bottom: 80px;
+}
+
+/* Don't capitalize names. */
+h5.doc-heading {
+  text-transform: none !important;
+}
+
+/* Don't use vertical space on hidden ToC entries. */
+h6.hidden-toc {
+  margin: 0 !important;
+  position: relative;
+  top: -70px;
+}
+h6.hidden-toc::before {
+  margin-top: 0 !important;
+  padding-top: 0 !important;
+}
+
+/* Don't show permalink of hidden ToC entries. */
+h6.hidden-toc a.headerlink {
+  display: none;
+}
+
+/* Avoid breaking parameters name, etc. in table cells. */
+td code {
+  word-break: normal !important;
+}
+
+/* For pieces of Markdown rendered in table cells. */
+td p {
+  margin-top: 0 !important;
+  margin-bottom: 0 !important;
+}

mkdocs.yml

@@ -0,0 +1,45 @@
+site_name: pycfmodel
+site_description: "A python model for Cloud Formation scripts."
+strict: true
+site_url: https://pycfmodel.readthedocs.io
+
+theme:
+  name: 'material'
+
+repo_name: Skyscanner/pycfmodel
+repo_url: https://github.com/Skyscanner/pycfmodel
+
+nav:
+  - Home: index.md
+  - Reference:
+    - CFModel: "reference/cfmodel.md"
+    - Resources:
+      - All Resources: "reference/resources.md"
+      - Common Properties: "reference/properties.md"
+  - Changelog: changelog.md
+  - Contributing: contributing.md
+  - Code of conduct: code_of_conduct.md
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - mkdocstrings:
+      watch:
+        - pycfmodel/
+
+extra_css:
+  - 'stylesheets/extra.css'
+
+extra:
+  social:
+    - type: 'github'
+      link: 'https://github.com/Skyscanner'
+    - type: 'twitter'
+      link: 'https://twitter.com/skyscannereng'
+    - type: 'linkedin'
+      link: 'https://www.linkedin.com/company/skyscanner/'

pycfmodel/model/cf_model.py

@@ -12,6 +12,25 @@
 
 
 class CFModel(CustomModel):
+    """
+    Template that describes AWS infrastructure.
+
+    Properties:
+
+    - AWSTemplateFormatVersion
+    - Conditions: Conditions that control behaviour of the template.
+    - Description: Description for the template.
+    - Mappings: A 3 level mapping of keys and associated values.
+    - Metadata: Additional information about the template.
+    - Outputs: Output values of the template.
+    - Parameters: Parameters to the template.
+    - Resources: Stack resources and their properties.
+    - Rules
+    - Transform: For serverless applications, specifies the version of the AWS Serverless Application Model (AWS SAM) to use.
+
+    More info at [AWS Docs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html)
+    """
+
     AWSTemplateFormatVersion: Optional[date]
     Conditions: Optional[Dict] = {}
     Description: Optional[str] = None
@@ -36,6 +55,15 @@ class CFModel(CustomModel):
     }
 
     def resolve(self, extra_params=None) -> "CFModel":
+        """
+        Resolve all intrinsic functions on the template.
+
+        Arguments:
+            extra_params: Values of parameters passed to the Cloudformation.
+
+        Returns:
+            A new CFModel.
+        """
         extra_params = {} if extra_params is None else extra_params
         # default parameters
         params = {}
@@ -67,6 +95,15 @@ def resolve(self, extra_params=None) -> "CFModel":
     def resources_filtered_by_type(
         self, allowed_types: Collection[Union[str, Type[Resource]]]
     ) -> Dict[str, Dict[str, Resource]]:
+        """
+        Filtered resources based on types.
+
+        Arguments:
+            allowed_types: Collection of desired types.
+
+        Returns:
+            Dictionary where key is the logical id and value is the resource.
+        """
         result = {}
         allowed_resource_classes = tuple(x for x in allowed_types if isinstance(x, type))
         for resource_name, resource in self.Resources.items():

pycfmodel/model/parameter.py

@@ -6,6 +6,10 @@
 
 
 class Parameter(CustomModel):
+    """
+    CloudFormation Parameter object representation
+    """
+
     NO_ECHO_NO_DEFAULT: ClassVar[str] = "NO_ECHO_NO_DEFAULT"
     NO_ECHO_WITH_DEFAULT: ClassVar[str] = "NO_ECHO_WITH_DEFAULT"
     NO_ECHO_WITH_VALUE: ClassVar[str] = "NO_ECHO_WITH_VALUE"
@@ -22,6 +26,19 @@ class Parameter(CustomModel):
     Type: str
 
     def get_ref_value(self, provided_value=None) -> Optional[str]:
+        """
+        Calculates the parameter value to be used in the template.
+
+        - If `NoEcho` property is set, it uses a constant value.
+        - If it is a list of numbers or a comma delimited list, returns the string version of each element in a list.
+        - Returns None if `provided_value` and `Default` are `None`.
+
+        Arguments:
+            provided_value: Value injected in the template
+
+        Returns:
+            The computed value.
+        """
         value = provided_value if provided_value is not None else self.Default
         if self.NoEcho:
             if provided_value is not None:

pycfmodel/model/resources/iam_group.py

@@ -7,13 +7,32 @@
 
 
 class IAMGroupProperties(CustomModel):
+    """
+    Properties:
+
+    - GroupName: Name of the group.
+    - ManagedPolicyArns: ARN of the IAM policies to attach.
+    - Path: Path to the group. See [IAM Identifiers](https://docs.aws.amazon.com/IAM/latest/UserGuide/Using_Identifiers.html).
+    - Policies: Inline policies embedded in the IAM group.
+
+    More info at [AWS Docs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-group.html)
+    """
+
     GroupName: Optional[ResolvableStr] = None
     ManagedPolicyArns: Optional[Resolvable[List[ResolvableStr]]] = None
     Path: Optional[ResolvableStr] = None
     Policies: Optional[Resolvable[List[IAMPolicy]]] = None
 
 
 class IAMGroup(Resource):
+    """
+    Properties:
+
+    - Properties: A [IAM Group properties][pycfmodel.model.resources.iam_group.IAMGroupProperties] object.
+
+    More info at [AWS Docs](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-group.html)
+    """
+
     TYPE_VALUE: ClassVar = "AWS::IAM::Group"
     Type: str = TYPE_VALUE
     Properties: Resolvable[IAMGroupProperties]