Gatsby: [discussion]: command line syntax refactoring in readme(s) for more beginer friendly

[LOLdevelopr]

Summary

A current status and PR for the implementation of the solution and
discussion till can be found https://github.com/gatsbyjs/gatsby/pull/17456

Relevant information

How a docs can be re written with examples https://github.com/gatsbyjs/gatsby/pull/17456#issuecomment-529095163

Detailed syntax descriptor can be found here http://docopt.org/

Environment (if relevant)

System:
    OS: Windows 10
    CPU: (4) x64 Intel(R) Core(TM) i5-6200U CPU @ 2.30GHz
  Binaries:
    Yarn: 1.15.2 - C:\Program Files (x86)\Yarn\bin\yarn.CMD
    npm: 6.9.2 - C:\Program Files\nodejs\npm.CMD
  Browsers:
    Edge: 42.17134.1.0
  npmPackages:
    gatsby: ^2.15.9 => 2.15.9
    gatsby-image: ^2.2.17 => 2.2.17
    gatsby-plugin-manifest: ^2.2.14 => 2.2.14
    gatsby-plugin-offline: ^2.2.10 => 2.2.10
    gatsby-plugin-react-helmet: ^3.1.6 => 3.1.6
    gatsby-plugin-sharp: ^2.2.20 => 2.2.20
    gatsby-source-filesystem: ^2.1.21 => 2.1.21
    gatsby-transformer-sharp: ^2.2.13 => 2.2.13

File contents (if changed)

gatsby-config.js: N/A
package.json: N/A
gatsby-node.js: N/A
gatsby-browser.js: N/A
gatsby-ssr.js: N/A

[muescha]

I would vote that we have a syntax like

syntax

gatsby new <site-name> [<starter-url>]

parameters:
<site-name> the folder where you create your new site. Can also be .
<starter-url> an URL to an Gatsby template (Default is: gatsbyjs/gatsby-starter-default)

examples

gatsby new my-app https://github.com/gatsbyjs/gatsby-starter-blog
gatsby new my-app https://github.com/netlify-templates/gatsby-starter-netlify-cms

[LOLdevelopr]

+1 for https://github.com/gatsbyjs/gatsby/issues/17473#issuecomment-52911878

its more clear and understandable.
just one thing

an URL to an Gatsby template (Default is: gatsbyjs/gatsby-starter-default)

here instead of gatsbyjs/gatsby-starter-default, better to have a full URL with gatsby-starter-default specifying the link

Like this

[gatsby-starter-default](https://github.com/gatsbyjs/gatsby-starter-default)

[muescha]

Ok

It's because you can leave off the GitHub part

[LOLdevelopr]

oh yeah I forgot its gonna be in github only right ! yeah true ! +1 for that

[LOLdevelopr]

We can mention that for the new command in gatsby-cli if leaving all the arg empty, a friendly prompts will appear in order to take those args

[anikethsaha]

This looks like a good idea. +1 for this !

[marcysutton]

I'm a fan of the syntax and examples sections. There are a few additional places in the docs source that would be worth updating as well (partly why we prompted to open an issue versus starting with a PR):

• https://github.com/gatsbyjs/gatsby/tree/master/docs/docs
• https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/starters.md
• https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-cli

[LOLdevelopr]

I will be starting it with this https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-cli .

[LOLdevelopr]

@muescha @marcysutton @sidharthachatterjee I would like to know if you guys are okay with this doc
gatsby-cli doc

Changes I made

• Added explained notes for new command here
• Added $ symbol in front of commands to visualize them better as CLI commands

[muescha]

in all examples there is no $ and thats not helpful if you double click for selecting a line

[muescha]

i would stick with http://docopt.org/ syntax at:

gatsby new <site-name> [<starter-url>]

or also
gatsby new [<site-name> [<starter-url>]] because you can leave off both names to get the command line prompt

[LOLdevelopr]

in all examples there is no $ and thats not helpful if you double click for selecting a line

okay will remove it then !

gatsby new [ []]

this one looks neat !

I will also remove the required word from the site-name argument details. as its not required for prompt!

[muescha]

with shell we become fancy color in github readme ;)

    ```shell
    gatsby new [<site-name> [<starter-url>]]
    ```

gatsby new [<site-name> [<starter-url>]]

[LOLdevelopr]

but this one will take the whole width ......

[marcysutton]

Closed with https://github.com/gatsbyjs/gatsby/pull/17549