[Django + Flask] Getting Started Frameworks section for Upsun

[gilzow]

This is a WIP/demo PR

Per conversation with Chad, demo PR of a reworked frameworks getting started section.

The idea is that the Frameworks section should include the required steps for a framework that are not covered by the general Getting Started guide. This way, if a user navigates to this section (e.g. "Deploying Drupal on Upsun") they should have the steps/items they need to accomplish the goal of deploying on Upsun for that framework without being taken away from the docs to a blog post. The blog posts then can focus on more niche items that are not appropriate for the documentation (e.g. setting up celerey on Upsun for Django).

What I don't like so far in this demo: we need a better, consistent method for organizing remaining steps and structure on how much additional information we include. In this demo, there are six remaining steps. I chose to organize by where the steps need to occur (.environment vs .upsun/config.yaml) but perhaps it needs to be an ordered list, one for each step?

For the first step (changes to.environment), I included information about why the environment variables are needed. Perhaps we don't need to include this information and we can instead assume that someone familiar with a framework already knows what the items are and simply needs to know where to include them?

[github-actions]

Your Platform.sh environment has successfully deployed. 🚀

See the site:
https://getting-started-demo-c6quj6q-ucq44jg6ofare.eu-5.platformsh.site/

[flovntp]

indentation changed?

[flovntp]

maybe you need to display all top level keys above, like;

applications:
    app:
        hooks:
            deploy: |

[flovntp]

and same for all other YAML snippets?

[gilzow]

that's the challenging part with yaml. do our code samples include the correct indentation according to where the keys we're changing are located so if someone copies and pastes they get the right indentation (assuming they're using 2 spaces per indent)? Or do we include the entire path (ie applications:<app-name>:hooks) and assume the user knows that they cant copy and paste the whole block?

I don't have a good answer.

[flovntp]

indentation is different...

[flovntp]

so, if it's an amendment to @chadwcarlson's Django blogpost, why don't you just change the snippets in the blogpost itself?
or, maybe add a note in the blogpost with the link to this page?

[gilzow]

@flovntp this is a demonstration of an idea i pitched to Chad. What is in this PR would replace the Django blog post. The blog post then would focus on adding celery to a django project, or some other topic that isn't a good candidate for the documentation.

The challenge I see with the current structure of the Upsun docs is, as a user, if I navigate to "Deploying Express on Upsun" in the documentation, there is zero documentation on the page on how to actually deploy an express app on Upsun. There are some generic getting started links, and general nodejs links, but nothing about Express. You have to scroll all the way to the bottom (which is "below the fold") to find a link to a blog post about how to possibly host an express app on Upsun.

IMO, most users are going to hit this page, see no relevant information immediately and bounce. Instead, my suggestion is to put the needed information directly on the page. Blog posts then should be reserved for topics that aren't good candidates for documentation.

[gilzow]

Added the section for Flask.

Not included is the information on how to change to alternative python web servers. Though we do have a whole section on python web servers with full instructions (/languages/python/server.html) so we could just add a note/link on this flask page.

I also don't like that i have both the .environment method for adding the environment variable as well as the config file method. We are inconsistent on their usage (I'm just as much at fault here as everyone else). On the one hand it demonstrates both are valid options and exposes the user to both options. On the other, it adds complexity and noise to the instructions.

We might need to consider an internally strategy/guidelines on when to use each method, at least for the documentation.

[chadwcarlson]

I couldn't comment directly, but we should update the Django topics to Flask topics, no?