[docs] Add command reference

[mattstein]

The Problem/Issue/Bug:

DDEV’s fundamental usage comes down to configuration and CLI commands, and the commands do not have a dedicated reference.

The closest we get is Using the ddev Command, which explains some commands and some usage.

How this PR Solves The Problem:

Fully Documents Commands + Options

This adds an exhaustive Commands reference page as a first step. Later PRs can focus the content of the command usage page and link to this new reference from other places in the documentation.

Minor fixes and improvements and improvements upon CLI help output:

• Links, when appropriate, to and from other relevant command descriptions.
• Adds comments to examples wherever I clearly understood them.
• Consistently uses my- as a prefix for user-specific names. (my-project, my-other-project, etc.)
• Fixes various typos and style issues consistent with [docs] Formatting and proper noun tune-up #4200.
• References popular npm package lerna rather than learna.
• Explicitly lists acceptable file formats when relevant, rather than using variations in examples.

Updates Navigation

This also adds a “Commands” item to the “Basics” sidebar and reorders items there for top-down urgency:

As the user I’ll first want to know how to broadly use DDEV’s commands, then what’s available, and come to reference/background information last.

Manual Testing Instructions:

You can test manually by checking out this branch and following these steps, or examine the automatic preview build.

Automated Testing Overview:

n/a

Related Issue Link(s):

#4188

Release/Deployment notes:

Purposefully does not touch any Golang or actual CLI output. That can come later if we want to improve parity. (Ideally we’d generate this entire reference page as part of the build process, but that’s a project for another day as well.)

[rfay]

I imagine basics needs updating, https://ddev--4354.org.readthedocs.build/en/4354/users/basics/

[mattstein]

I agree, and I’m working on a much broader effort to improve organization and overall framing—breaking it into discrete PRs with this one being the first.

In that broader effort, “Basics” is “Usage” and starts like this:

^ That part’s still only half-baked because there’s a lot more going on with each of the sections, with pretty deep reorganization and some new content to introduce things and tie them together.

I figure this PR is an easy enough place to start since it’s nicely self-contained.

[mattstein]

This page is ready to merge if/whenever you’d like, though.

[rfay]

This is what I was pointing out above, just that these should match each other.

[mattstein]

Ohhhhh! I was looking at “Learn”, which without any punctuation seems kind of like a typo or an unfinished sentence or a command that might be grunted by a caveperson. I shall update that list right now.

[rfay]

Would you mind making another pass for links into docs? It seems to me like this is the time to do it. This is an awesome addition, and more so if people can find their way to the relevant background.

[mattstein]

Would you mind making another pass for links into docs?

Will do!

[rpkoller]

one minor comment.i've skimmed through the commands.md and noticed that ddev delete is missing one small but important detail from my perspective. usually each command has just flags available. but in that case there is a "sub"command ddev delete images

Removes all ddev project information (including database) for an existing project, but does not touch the project codebase or the codebase's .ddev folder

Usage:
  ddev delete [projectname ...] [flags]
  ddev delete [command]

Examples:
ddev delete
ddev delete proj1 proj2 proj3
ddev delete --omit-snapshot proj1
ddev delete --omit-snapshot --yes proj1 proj2
ddev delete -Oy
ddev delete --all

Available Commands:
  images      Deletes drud/ddev-* docker images not in use by current ddev version

Flags:
  -a, --all                Delete all projects
      --clean-containers   Clean up all ddev docker containers which are not required by this version of ddev (default true)
  -h, --help               help for delete
  -O, --omit-snapshot      Omit/skip database snapshot
  -y, --yes                Yes - skip confirmation prompt

Global Flags:
  -j, --json-output   If true, user-oriented output will be in JSON format.

Use "ddev delete [command] --help" for more information about a command.

for me it was one of the most convenient ways to remove the dangling images not used by the current version of ddev.

but overall amazing work! thank you! i really like the approach and thoroughness!

[mattstein]

Oh you’re right @rpkoller, I totally missed that sub-command. Will add—thank you!

[mattstein]

Documented the missing delete images subcommand and added a lot of links to and from this new Commands page and the Config Options page. Linked clean command to “Uninstalling DDEV” page.

[rfay]

Wow, you went nuts! I wasn't asking for all links inbound to the new page to be updated :) Just for the things on this page to have links to context about them! Great improvements. Now reading the actual command reference.

[mattstein]

Wow, you went nuts! I wasn't asking for all links inbound to the new page to be updated :) Just for the things on this page to have links to context about them! Great improvements. Now reading the actual command reference.

I’d planned on doing exactly this after re-arranging pages, since links are useful in both directions. More to update in the near future, but a more useful PR right now as you suggested.

[rfay]

Fantastic, thanks. I know we'll want to fiddle with it as time goes on, but what a great thing.

let me know when ready to pull.

[mattstein]

Pull away, sir!