Redwood: CLI Docs and Development

[thedavidprice]

_continuing conversation from_ #310

There's not much separation currently between docs meant for _using_ Redwood (e.g. building apps) and those for _developing_ Redwood. Currently, docs lives within either the /redwood repo or /create-redwood-app repo. The rwjs.com site has a list of docs to parse, gets them, and displays on the site. So depending on which context you're accessing docs, it can be a bit unclear what they're meant for. And even more unclear when we combine both _types_ of docs into one.

• [ ] Todo: separate cli 'how to contribute' information from 'how to use' information
  
  
  
  • [ ] Edit this doc: https://redwoodjs.com/guides/command-line-interface
  
  
  • move _contributing_ specific content to Framework cli/ README
  
  
  • reference link between (to and from) this doc and Framework README
  
  
  • reference link between (to and from) this doc and reference section "Command Line Interface"
  
  

Secondly, our current yarn rw help output isn't all that informative or helpful (yet). I super ❤️ adding the completion shortcuts #311 but we still need to add/improve help text.

• [x] Todo: audit all cli commands and options; fill in missing and outdated descriptions

Thirdly, it seems very standard for library/framework documentation to contain cli command-specific docs. And for our project where we'll be increasingly leaning into cli, it will be a necessity and also an entry point for understanding the Redwood approach. We're learning through feedback about our site and tutorial that people definitely experience the quality of this project as a whole, including the code + documentation as a single unit of evaluation.

• [ ] Todo: create cli 'how to use' doc

Examples

Examples of full cli documentation:

• Rails command line
• Prisma cli
• Gatsby cli

Example of "point users to help" cli documentation:

• Nextjs cli

Discussion

All that said, yes, keeping up with docs is hard work in a rapidly evolving framework. We'll need to allow for things to get behind and be a bit messy. But we should also be thinking toward how we can improve processes so we can collaboratively keep things in sync (e.g. maybe a PR template checklists, etc.)

And I also think we're pushing up against our current system of not having a tool to manage/generate documentation from one place (e.g. Docz, etc.). So maybe it's time to evaluate that as well.

Could you all please add some comments here for discussion? I don't mind if the topics wonder a bit from CLI specificity as long as we are addressing the general topic of documentation and how to both build a foundation and set a direction + vision.

Thanks!

[jonniebigodes]

glad to know that the cli is getting some tlc. As the following output is still occuring when using yarn rw --help

index.js <command>

Commands:
  index.js build [app..]    Build for production.
  index.js db <command>     Database tools.                  [aliases: database]
  index.js dev [app..]      Run development servers.
  index.js generate <type>  Save time by generating boilerplate code.
                                                                    [aliases: g]
  index.js lint             Lint your files.
  index.js open [port]      Open your project in your browser.
  index.js test [app..]     Run Jest tests for api and web.

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
Done in 31.59s.

The index.js bit is something to be taken into consideration. Also good that you're already considering the documentation site, i was going over the docs in more detail and was considering proposing a approach like the gatsby cli to give the readers current and future ones a more approachable documentation.

[thedavidprice]

@jonniebigodes Remind me, are you on Windows machine? From my Mac running yarn rw help I see

rw <command>

Commands:
  rw build [app..]    Build for production.
  rw db <command>     Database tools.                        [aliases: database]
  rw dev [app..]      Run development servers.
  rw generate <type>  Save time by generating boilerplate code.     [aliases: g]
  rw lint             Lint your files.
  rw open [port]      Open your project in your browser.
  rw test [app..]     Run Jest tests for api and web.

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
✨  Done in 1.49s.

@bcoe is this a windows/mac Yargs settings we didn't config correctly?

[jonniebigodes]

@thedavidprice yes running a windows 10 box. That behaviour happens with both cmd and the terminal preview. I'll check the powershell and report back to see if the same happens shortly

[weaversam8]

Same happens in Powershell as well.

[jonniebigodes]

ok...that covers it then...thanks @weaversam8

[bcoe]

@thedavidprice not 100% sure what's going on here, but try:

.scriptName("redwood"), which will allow you to explicitly set the application name.

If you can figure out a unit test that fails on Windows but passes on *nix, would love the PR 👍

[thedavidprice]

@jonniebigodes @weaversam8 Working on a fix via PR #331

@bcoe Thanks for the help! Implemented in PR above 🚀

[jonniebigodes]

@thedavidprice i got the notification and i'm going to keep an eye on this.

[weaversam8]

Can confirm that #331 fixes the issue here, this is working as intended in v0.3.0 on Windows.

[jtoar]

Link to the (very rough) cli README google doc

@thedavidprice Following up from #423 here. Let me know if I should open a new issue instead. But I think some aspects of the discussion are relevant.

Todo: separate cli 'how to contribute' information from 'how to use' information

I think the cli README should both tell you how to use it and how to contribute to it. My thinking is: while drafting the api README, I didn't have to think about usage because there's not much for a user to do, but in the (very near) future it seems very likely that that there will be--so unless we plan to split those up too, I don't see top-level sections as confusing/vague:

# CLI
## Purpose and Vision
...
## Usage
## Contributing

That said, should I shelve the cli README for now and get to work on a cli 'how to use' doc?

Last point of contention: There's a Reference section in the google doc. As a user, this kind of section is really important--just to see a list of all the commands!--and could probably be auto-generated once all the commands are documented internally. (I.e. I don't think it'd be that big of a maintenance problem.)

[thedavidprice]

quick note:
In contributing README, need to add a couple requirements

• all commands must be cross-platform (Windows & Mac)
• we need tests for new commands (and help to backfill tests for current commands)

[thedavidprice]

CLI audit: commands + options needing "descriptions"

• [x] yarn rw g auth Needs to list all "provider" options
• [x] rw g page <name> [path] should we include "path" in description?
• [x] rw g sdl <model> add this text: "based on a given DB schema Model". Also, here it is called a "service object" but in g service <name> it's a "service component". Let's standardize 'cause it's the same thing just used in different ways. (Right?)

[jtoar]

@thedavidprice I don't mind picking some of this up too, especially the todo in the original comment:

Todo: audit all cli commands and options; fill in missing and outdated descriptions

In general it seems like the builder for all commands should be a function instead of an object so we can use yargs.positoinal.

[thedavidprice]

@jtoar Hey, thanks! I was just about to loop you in here -- trying to catch up with all the great work you've been cranking out.

Audit --> done! That list (two comments) above includes the only updates/additions I think need to be made.

But, yes, would be great to have your help with three things to wrap this up:

1. explore use of .positional -- is it better behavior? Propose PR if so
2. definitely update those three commands' I listed above (and others as you see needed)
3. explore "completion shortcuts" suggestion in #311 See Yargs Doc here.

Thoughts?

[jtoar]

Audit: More might need to be updated, at least if we want super-consistency with the CLI Reference. One example off the top of my head: in the CLI Reference, I list the argument to build and dev as [side..] instead of [app..].

I kind of took that liberty thinking I'd make a full sweep of the CLI commands afterwards. I'll do a full audit for consistency and get your + other's take on which language is better?

Positional Will do that. As a quick example, here's a diff of yarn rw g page --help with positionals:

~/redwood-app$ yarn rw g page help
yarn run v1.22.4
$ /redwood-app/node_modules/.bin/rw g page help
rw g page <name> [path]

Generates a page component.

+ Positionals:
+   name  Name of the generated page.                          [string] [required]
+   path  Path to the page. Default is name.                              [string]

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]
  --force                                             [boolean] [default: false]
Done in 1.30s.

Completion shortcuts Yes!

[thedavidprice]

zOMG... Yes, please, I want positionals!! 🤩

Audit: ah, makes sense and I'm all for it.

Completion shortcuts ✅

[thedavidprice]

_Update:_ I made some edits to the first comment related to updating the CLI Guide doc.

@jtoar @cannikin --> Question about the https://redwoodjs.com two doc sections, Guides and Reference: _At this time, should there be these two, separate sections, or should they be combined?_

This is highlighted by the current work on the CLI documentation -- we currently have two docs named "Command Line Interface", one in each section but containing very different types of content. We'll soon link the two docs appropriately, but is this a good UX implementation or a work around -- especially challenging to me is having two docs with the same name... ?

I see a clear distinction between types of content. And, in the future, I believe our trends in doc visitors will be more people who "just want to find the option or API needed to do X." But I don't believe our current implementation makes it 1) clear as to this distinction and 2) obvious there are two sections. This could be a simple menu structure change, e.g. put Guides and Reference next to each other, or add structure by creating a "Docs" top menu and include Guides and Reference within it, or ??

What say you all?

[jtoar]

@thedavidprice Having a hard time answering this one. I'm gonna say yes? But some back and forth would help. Here's what I'm thinking:

• One thing that's making this hard for me is that there's no bona fide guide. The docs from the repo that were moved into Guides haven't really been fleshed out since they've gotten there (and not for no good reason, there's been more than a lot to do!). So Guides need to step it up! :muscle:

• Guides need to step it up part 2: "Read the Guides" is the secondary button next to "Start the Tutorial". So we want users to go there.

• As to why Reference might not matter much yet: if you're using Redwood, you're pretty much using all it has to offer. The Redwood API just doesn't seem large enough yet to need to be separated from usage.

So yes, but I think the real problem is that over half the guides kind of pale in comparison to the Tutorial/Cookbook and need to be given some real firepower and a strong identity.

[thedavidprice]

Here's my proposal for next steps:

1. combine "Guides" and "Reference" into one section named "Docs". NOTE: I think we should still structure docs that are primarily for Reference _as_ reference docs. It's just the current menu structure that doesn't make sense to me to keep 'em in two sections.
2. first doc is "Introduction" (can we visually emphasize this as a priority and/or unique doc?), all following docs should be listed alphabetically
3. CLI
   
   
   
   • combine into one doc starting with "How To" and the bulk afterwards from "Reference" content (NOTE: I don't think there's much to keep from current "Guide". Dom, you wrote a much better "How To" section at one point)
   
   
   • The Menu Title should probably be "CLI" (or maybe "CLI (Command Line)"). For search keywords, is it possible to use the opposite of the menu name as the doc title... or make sure both are included in the intro paragraph for search index?
   
   
   • any contributing content should be moved to CLI package README, which this doc can link to
   
   
4. No titles should include "Redwood", e.g. "Redwood Forms" and "Redwood Router" should be "Forms" and "Router". But, since some of these are the READMEs for NPM package page, can the page titles still be "Redwood Forms", etc.? (Note: if so, we might want to change the title of the "Authentication" page to be "Redwood Auth".
5. "Redwood's HTTP server for serverless Functions" is a mess. (Maybe the title specifically.) Two things:
   
   
   
   • Move appropriate content to the redwood.toml doc section web.apiProxyPaths
   
   
   • Rename this to "Serverless Functions", which should cover 1) how Redwood functions work in general, how the code is structured, and reference to the CLI function generator and 2) how the GraphQL function works and the apiProxyPath setting
   
   
6. lastly, what should the menu item for "App Configuration: redwood.toml" be named? I created it as-is for keyword/search, but is it clear and/or should it be "redwood.toml App Configuration"?

What say you @cannikin and @jtoar?

[jtoar]

1. I'm on board with this for the time being. When it needs to be, the reference should be easy to reconstruct. And +1 for the title.

2. Rails has the rails doctrine. I feel like the Introduction could be marketed in a similar way? Like:

1. I think I still have it somewhere. Once I get the go-ahead, I'll throw up another PR with those changes. And I'd prefer just "CLI" or "Command Line". "CLI (Command Line)" seems too redundant?

For search keywords, is it possible to use the opposite of the menu name as the doc title... or make sure both are included in the intro paragraph for search index?

I can look into this.

1. If the goal's to make the docs on the website and the docs in the repo distinct, should we copy them over to redwoodjs.com so we can 1) avoid repo referencing and 2) start making them different?

2. All for it!

3. Both of those seem clear. Another suggestion: "Configuring your App: redwood.toml".

[cannikin]

We used to have a single section called "Docs" and then we talked about it and decided to split it out to "Guides" and "Reference"... you for sure want to go back to a single section again? The way I see the two sections:

• Guides are prose that walk you through how to use something, like the Router document
• Reference are the hardcore, dry, technical description of each and every option, like the Forms document

Do you think we don't have enough Reference items to give them their own complete section? That number will (hopefully) keep growing and it does seem like they're distinct from the more story-like Guides. It would be a shame to combine them only to split them back out again in a couple of months.

Are we getting complaints that people can't find the docs they need or is this a gut feeling that things could be organized better?

[cannikin]

I love that idea of a top-level "Redwood Way" link!

[jtoar]

@thedavidprice @cannikin started this at https://github.com/redwoodjs/redwoodjs.com/pull/149. I'll keep it as a draft until we decide for sure. Since combining the sections also means combining some of the files together (in the case for the cli), I'll make content modifications a part of that PR as well? I'll try to keep the commits modular/squash them so that we have flexibility.

[thedavidprice]

@jtoar Is the remaining task here the CLI contributing README work? Looks like you've hammered on everything else unless I’m missing something.

[jtoar]

The CLI contributing README for sure, and the third todo, "create cli 'how to use' doc", is in the works. Plus the reference needs an update after #594, which I was doing simultaneously but just didn't publish yet.

Other than those two things... I think you mentioned adding recommendCommands or something similar to yargs, but I can't remember where we were discussing it. Trying to dig it up now.

[thedavidprice]

Roger that. And thanks!

I think you mentioned adding recommendCommands or something similar to yargs, but I can't remember where we were discussing it. Trying to dig it up now.

^^ I did. But I don't think it's worth the effort at this time (nor have I explored what the benefits would be... was just a curiosity for potential improvement).

There are a lot of other docs that would be a higher priority if you're available + interested 😁