Docs cli update improvement #3173
Conversation
…ovement Merged veeba's contribution to my local branch
…ions to provide more context to a beginner what a cli is, and added the requirements needed to follow the tutorial
…ent commands not interacting with a system, which sounds generic
…nd the scope of the tutorial. kept it simple and clean for users to see what command to run.
…s removing powershell links. And uses the myst format for links
… command-line-tutorial to keep the naming convention consistent as used in the docs folder
|
Please note that you can just forcepush to your PR branch, no need to recreate/reopen PRs |
|
@ThiefMaster Noted. I didn't want to overwrite the history. |
| @@ -0,0 +1,173 @@ | |||
| # Command line basics — Introduction to command line interfaces (CLIs) | |||
|
|
|||
There was a problem hiding this comment.
Change to Command Line Basics
| This short, hands-on tutorial gives developers the minimal set of command-line skills needed to start using or building Click-based CLIs. | ||
| It is written for beginners who may have little or no command line experience. | ||
| All examples provide commands for both macOS/Linux (Bash) and Windows (cmd). | ||
|
|
There was a problem hiding this comment.
Rephrase: This tutorial shows the developer the basics of using the command line. It should take about 20 minutes to complete.
The user will see the multishell support so no need to mention it. The title already conveys that this is for beginners.
| ``` | ||
|
|
||
| First Let's understand what a command line interface is. | ||
|
|
|
|
||
| A Command Line Interface (CLI) is a text-based way to interact with your computer. | ||
| Instead of clicking icons or buttons, you type commands into a terminal or console window. | ||
| CLIs are powerful tools for developers and system administrators because they allow for automation, scripting, and remote access to systems. |
There was a problem hiding this comment.
Rephrase: Instead of clicking icons or buttons, you type commands into a terminal.
| The shell parses the command, identifying the action, options, and arguments. It locates the command in the system’s PATH and executes it. The system returns output (e.g., data, error messages) to the CLI. | ||
|
|
||
| ## What you will learn | ||
|
|
There was a problem hiding this comment.
Remove this section. Change the headings so that the contents directive will do this work for you.
| - Search inside a file (grep-style) | ||
| - View a CLI's help output | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Remove. Every computer has these things.
| - Creating and editing small files is how you try things quickly from the terminal without opening a full IDE. | ||
| - Grep-style searching is essential for finding text in logs, configs, or code. | ||
| - Most CLIs expose `--help` (or `-h`) which documents commands, options, and usage. | ||
|
|
There was a problem hiding this comment.
You have the right idea with the commands and explanations but they need to be interwoven and gone through one by one. Use the tabs shown in the virtualenv tutorial to go through them one by one. I realize this will make you use restructured text for the blocks. Once all the docs are markdown, I plan to find a suitable replacement for the plugin that will work for myst.
There was a problem hiding this comment.
Actually looks like Sphinx-tabs supports myst as of 2020, so should be good. https://github.com/executablebooks/sphinx-tabs/blob/master/CHANGELOG.md#130---2020-09-08
|
@HanslettTheDev @Veebaa Good job! Don't be put off by the number of comments. Good tutorials always require a good amount of back and forth. |
|
Thank you. I'll make the changes as requested |
4 participants
This PR maintains the history of @Veebaa
This PR aims to close issue #3076 and continues from where Veeba left of