Sceptre: Update Documentation for v2.0

[ngfgrant]

CONTEXT

Much has changed in Sceptre version 2. We have added a couple of new concepts, renamed environments, and made changes to the API to make using sceptre more succinct and cleaner.

TASKS

• Update sceptre/docs/docs/install.md to include a full example including the setup of a virtual env.

• Update sceptre/docs/docs/get_started.md to correct CLI commands and rename of environment.

• Update sceptre/docs/docs/terminology.md to correct for the Environment rename. Add a more complete glossary.

• Update sceptre/docs/docs/cli.md to correct v2 CLI commands.

• Update sceptre/docs/docs/environment_config.md to account for ConfigReader, renaming of Environments, and CLI / python module changes.

• Update sceptre/docs/docs/stack_config.md to account for ConfigReader and renaming of Environments.

• Small changes required to sceptre/docs/docs/templates.md to account for support of any template extension. Maybe a couple extra examples and checking for any old terms such as Environment.

• Small changes required to sceptre/docs/docs/hooks.md to remove any redundant deprecation warnings and check for concepts that have been renamed.

• Small changes required to sceptre/docs/docs/resolvers.md to remove any redundant deprecation warnings and check for concepts that have been renamed.

• Update sceptre/docs/docs/resolvers.architecture.md to account for renamed terms and ConfigReader. Maybe this content is a good starting point for tutorials and walkthroughs?

• Update sceptre/docs/docs/faq.md with most frequently asked questions and a link to tagged stackoverflow questions?

• Update sceptre/docs/_api/ - should be done automatically via Sphinx. Need to keep v1 docs for reference.

Sceptre Examples

Having more walkthroughs and examples of how you can structure a project with Sceptre is something that will benefit the community.

I propose a separate space in the official docs where community members can submit articles on how they have structured their projects and the pros and cons of their approaches. There might be scope to have some sort of standard template for these articles which might bring consistency to the writing/layout. The articles should stress that there is no "right way" to set up a project, however, there might be some anti-patterns that emerge that we would want to highlight.

Tools

I have previously used Gitbook which has worked well and offer some nice off-the-shelf templates for guides, API references, and Help Centre. We will probably end up with V1 docs and V2 docs. Plays nice with Github Pages which now allows custom urls via CNAMEs.

[radhikasundararaman24]

Hello: I'm pitching in to help the community with some documentation support. What kind of doc support we need for this? Also, can you share the links to existing resources?

[1oglop1]

This issue will serve as an aggregator for what's missing in documentation.
Once #389 and #412 is resolved, it will be good to split this into separate issues.

Issue: Sceptre documentation silently assumes prior CloudFormation knowledge.
Issue: Command description is somewhat vague - it's very unclear what execute does.

$ sceptre execute-change-set --help
Usage: sceptre execute-change-set [OPTIONS] ENVIRONMENT STACK CHANGE_SET_NAME

  Executes the change set.

  Executes ENVIRONMENT/STACK's change set with name CHANGE_SET_NAME.

---

Action points:

• [ ] Write down information about configuration lifecycle
• [ ] Provide necessary knowledge and links with CF commands in documentation but also CLI

---

Here is an example example how the sceptre should provide the necessary link when we wrap original commands without change.
Look at this example:
https://elasticsearch-py.readthedocs.io/en/master/api.html#snapshot

Explanation is pretty brief (though effortless) and contains hyperlink to original API documentation.
This should provide necessary biding between sceptre and it's dependencies.

---

CLI documentation can be done using sphinx-click plugin. It would require add more information to the CLI docstrings.
usage example: https://github.com/1oglop1/sceptre/commit/b7aeacaa08feeec6a964e2610015785c62de95b1

[1oglop1]

@rdkr @ngfgrant Live version of RTD
https://beta-doc-sceptre.readthedocs.io/en/sphinx-doc/#

To update docs, all I needed was to push to the branch.
EDIT: (demo has been shut down as per request below)

[ngfgrant]

Nice work on the rst/sphinx conversations. The CLI doc tool seems to work nicely as well. Could I ask that those docs are taken off RTD for the time being though?

[1oglop1]

@ngfgrant yeah no problem, it was just for the demo.

[ngfgrant]

V2 Docs have been updated and deployed. Still need to do #430