New move machines (superfly#457)

* feat: moving machines into separate namespace

* wip

* wip

* wip

* wip

* collect more stuff under machines (superfly#450)

* collect more stuff under machines

* remove unrelated change from branch

* forgot a menu item

* use title case

* remove empty rhs nav

* shorter filename

* wording tweaks

* make nav match title

Co-authored-by: divya <hello@shortdiv.com>

machines/guides-examples.html.md

@@ -0,0 +1,6 @@
+---
+title: Guides and Examples
+layout: framework_docs_overview
+toc: false
+order: 3
+---

app-guides/functions-with-machines.html.md.erb → machines/guides-examples/functions-with-machines.html.md.erb

@@ -1,12 +1,13 @@
 ---
-title: Running user code on Fly Machines
-layout: docs
+title: Run User Code on Fly Machines
+layout: framework_docs
 sitemap: false
 author: joshua
 categories:
   - machines
 nav: firecracker
 date: 2022-05-20
+redirect_from: /docs/app-guides/functions-with-machines/
 ---
 
 [Fly Machines](/docs/reference/machines) are [Firecracker VMs](https://firecracker-microvm.github.io/) with a fast REST API that can boot instances in about 300ms, in any region supported by [Fly.io](https://fly.io/docs/reference/regions/).
@@ -32,7 +33,7 @@ Here we'll use a [simple Fastify server](https://github.com/fly-apps/fastify-fun
 
 Pick a unique name and create the required application to group machines together. This application is also the gateway to accessing the machines from the internet.
 
-<%= partial "../reference/machines/create_app" %>
+<%= partial "/docs/reference/machines/create_app" %>
 
 Note the `network` field. This is necessary to isolate the app from other private networks on the organization.
 
@@ -46,35 +47,35 @@ fly ips allocate-v4 -a user-functions
 
 Launch a user machine by supplying a Docker image and a networking configuration. We can also [configure the machine's memory/CPU](https://fly.io/docs/reference/machines/#create-and-start-a-machine).
 
-<%= partial "../reference/machines/launch_req" %>
+<%= partial "/docs/reference/machines/launch_req" %>
 
 Machines are permanent, so keep the ID from the response handy.
 
 Your users' service will boot immediately after this API call. Launch speed is a function of image size. Tiny images should boot in less than 2 seconds. Large, complex images are much slower to boot.
 
 Try accessing your new machine at `https://user-functions.fly.dev`. If no requests arrive within 4 seconds, the machine will exit, but a request will force it to start back up automatically.
 
-## Launch in another region
+## Launch a Machine in another region
 
 That machine was launched in the region nearest to you. Say you want your user function to run fast for users in Australia. Let's launch another machine there.
 
 The Anycast IP you allocated will route traffic to the nearest region with a deployed machine. If it's stopped, it will start up automatically.
 
-<%= partial "../reference/machines/launch_syd_req" %>
+<%= partial "/docs/reference/machines/launch_syd_req" %>
 
-## Stopping a machine
+## Stop a machine
 
 In a FaaS environment, you'll usually want to wait for a machine to exit. You can stop them with an API call, however, if needed.
 
-<%= partial "../reference/machines/stop" %>
+<%= partial "/docs/reference/machines/stop" %>
 
 ## Start an existing machine
 
 Once created, a machine may be stopped and started until you delete it. The good news is, images stay cached after first launch. Starting an existing machine is very fast.
 
 Use the existing machine ID again to start it:
 
-<%= partial "../reference/machines/start" %>
+<%= partial "/docs/reference/machines/start" %>
 
 The start API call only returns successfully if the machine is in a stopped state. It's safe to call start on a running machine, though. If you're unsure of the machine state, just call start and ignore the error response.
 
@@ -102,13 +103,13 @@ Here we see that one of the machine exited itself.
 
 The equivalent API call for such an overview:
 
-<%= partial "../reference/machines/list_req" %>
+<%= partial "/docs/reference/machines/list_req" %>
 
 ## Delete a machine
 
 When you're done, delete the machine:
 
-<%= partial "../reference/machines/delete" %>
+<%= partial "/docs/reference/machines/delete" %>
 
 
 ## Additional notes

app-guides/terraform-iac-getting-started.html.md.erb → machines/guides-examples/terraform-machines.html.md.erb

@@ -1,6 +1,6 @@
 ---
-title: Getting started with Terraform and Machines
-layout: docs
+title: Getting Started with Terraform and Machines
+layout: framework_docs
 sitemap: false
 nav: firecracker
 author: dov
@@ -9,6 +9,7 @@ categories:
   - iac
   - terraform
 date: 2022-07-08
+redirect_from: /docs/app-guides/terraform-iac-getting-started/
 ---
 
 [Fly Machines](/docs/reference/machines) are [Firecracker VMs](https://firecracker-microvm.github.io/) with a fast REST API that can boot instances in about 300ms, in any region supported by [Fly.io](https://fly.io/docs/reference/regions/).

machines/index.html.md

@@ -0,0 +1,15 @@
+---
+title: "Fly Machines"
+layout: framework_docs_overview
+toc: false
+redirect_from: /docs/reference/machines/
+---
+
+Fly Machines are [Firecracker VMs](https://firecracker-microvm.github.io/) with a fast REST API that can boot instances in about 300ms, in any region supported by [Fly.io](https://fly.io/docs/reference/regions/).
+
+The Machines API gives you efficient, low-level control over VM provisioning, supported by Fly.io infrastructure and networking features.
+
+Machines are also the spawning ground for new platform features like *wake-on-request* (also known as *scale-to-zero*). You can
+stop a running machine to save on compute costs. It then may be started automatically when a request arrives at the Fly proxy.
+
+[Read the Fly Machines announcement post.](https://fly.io/blog/fly-machines/)