Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Update documentation #74

Open
CrowdboticsDocs wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update documentation #74

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 88 additions & 59 deletions index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ const gitRoot = () => {
} catch {
invalid(
`This command must be executed inside a git repository.
Visit our official documentation for more information and try again: https://docs.crowdbotics.com/creating-reusable-modules`
Visit our official documentation for more information and try again: https://docs.crowdbotics.com`
);
}
};
Expand Down Expand Up @@ -414,65 +414,94 @@ demo`;
console.log(`usage: cb <command>

Commands available:
parse Parse and validate your modules
demo Generate a local React Native and Django demo app
add Install a module in the demo app
remove Remove a module from the demo app
create Create a new module of a given type
commit Update an existing module from the demo source code
init Initialize a blank modules repository
upgrade Upgrade your existing app's scaffold to the latest version
help Show this help page
feedback Send feedback to Crowdbotics to let us know how we're doing
login Login to your Crowdbotics account. Requires 2FA authentication
logout Logout of your Crowdbotics account
publish Publish your modules to your organization's private catalog
modules Manage modules for your organization

Parse and validate your modules:
cb parse --source <path>

Parse modules and write the data to a json file:
cb parse --source <path> --write <path>

Create a demo app:
cb demo

Create a module of a given type:
cb create --name <module-name> --type <all/react-native/django>

Initialize a modules repository:
cb init --name <my-modules-repository-name>

Upgrade your scaffold to the latest master:
cb upgrade

Upgrade your scaffold to a specific version (git tag, git commit or branch name):
cb upgrade --version 2.3.0

Install one or modules to your demo app:
cb add <module-name> <module-name-2>

Remove one or modules from your demo app:
cb remove <module-name> <module-name-2>

Install modules from other directory:
cb add --source ../other-repository <module-name>

Install modules to other app that is not "demo":
cb add --project ../other-project <module-name>

Remove modules from app that is not "demo":
cb remove --project ../other-project <module-name>

Update a module definition from the demo app:
cb commit <module-name>

Update a module definition from other app:
cb commit <module-name> --source <path>

Glossary:
<module-name> stands for the name of the directory where the module is defined.
add: Installs one or more modules into your Demo app.
commit: Updates the definition of an existing module.
create: Creates a new module of a specific type.
init: Initializes a new blank modules repository.
login: Logs in to your Crowdbotics account.
logout: Logs out of your Crowdbotics account.
modules: Manages modules for your organization.
parse: Parses and validates module definitions.
publish: Publishes your modules to your organization's private catalog. When run, this command prompts for more information.
remove: Removes one or more modules from your Demo app.
upgrade: Upgrades your existing app's scaffold to the latest version or a specific version.

--------------------
More details
--------------------

add: Installs one or more modules into your Demo app.
Arguments:
--source: (Optional) Specifies the source directory for modules (defaults to the Crowdbotics modules directory based on package location).
--project: (Optional) Specifies the project directory to install modules into (defaults to the git root of the current working directory).
Parameters:
<module1> <module2>: Names of the modules to install (required).
Example: cb add module1 module2
Comment on lines +435 to +440
Copy link
Collaborator

@danielsousaio danielsousaio Apr 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit pick on the language used here.

First let's look at the entire command:

cb add module1 module2 --source something --project foobar

That's 8 arguments as far as the shell is concerned (space is the separator), and one can access them in bash via $0 through $7.

First argument is cb, second is add, the last is foobar, etc.

But when it comes to building man pages, we usually call the various arguments differently depending on their syntax and position - they can be called "command", "subcommand", "argument" (or positional argument), "parameter" and "option".

With that in mind, here's a few examples:

cb add module1 module2 --source something --project foobar
^^
command

cb add module1 module2 --source something --project foobar
   ^^^
subcommand

cb add module1 module2 --source something --project foobar
       ^^^
argument or positional argument

cb add module1 module2 --source something --project foobar
                       ^^^
parameter (parameter with value "something" for the option "source")

cb add module1 module2 --source something --project foobar --flaglongform
                                                           ^^^
option (also known as flag and in the long form syntax)

cb add module1 module2 --source something --project foobar -f
                                                           ^^^
option (also known as flag and in short form syntax)

Copy link
Collaborator

@danielsousaio danielsousaio Apr 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PS: Most man pages just refer to all arguments as options and the only distinction is syntax. See this git-add man page for example:
https://git-scm.com/docs/git-add

Copy link
Collaborator

@danielsousaio danielsousaio Apr 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TL;DR - calling everything generically an option is fine, but when you want to be precise we should be consistent in the language.

Also, this is the "help" command output, this shouldn't be an exhaustive reference or man page of all commands. Even man pages are divided by subcommands. Perhaps its best if we put --help and -h on all commands and just show the command/options part for each.

Copy link
Author

@CrowdboticsDocs CrowdboticsDocs Apr 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • I'm fine with any changes you want to make. @codydjango noticed some grammar issues.
  • There is a bit of disagreement on the help page. Some folks say the man page should be the complete version and the docs should be just an overview, so users can find everything the need at the command line. Others have suggested, as you have, that the man page shouldn't be exhaustive. Either way, we need to have an exhaustive list somewhere.
  • Also, @codydjango did ask for a --help on "cb" as well. Yes, you get the full list if you just type "cb" . But devs are used to the --help functionality.

Copy link

@codydjango codydjango Apr 12, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, I did but I'm willing to defer to @danielsousaio.

Daniel, I did ask Marni to review the docs because I noticed some typos and awkward phrasing. It was a few weeks back, so the worst offenders might have already been addressed.

What do you think? Should we disregard the PR, or are there specific changes that can be done to move this forward?

Copy link
Collaborator

@danielsousaio danielsousaio Apr 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Others have suggested, as you have, that the man page shouldn't be exhaustive. Either way, we need to have an exhaustive list somewhere.

Yes, I'm suggesting that we make cb --help or cb help short and concise. A description, a list of the subcommands, and a few common commands examples.

Then on each subcommand do i.e cb add --help or cb help add with full list of all the options available for that command and the details for each.

Copy link
Collaborator

@danielsousaio danielsousaio Apr 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we disregard the PR, or are there specific changes that can be done to move this forward?

I don't think we should disregard the PR, it's a nice start to improving the help docs - I just think it needs some cleanup.

Copy link
Collaborator

@danielsousaio danielsousaio Apr 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can collaborate with you @CrowdboticsDocs here, and implement the "help" per subcommand.

Copy link

@codydjango codydjango Apr 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@danielsousaio I totally agree, I think your suggestion is great: a short and concise cb --help and then each subcommand has it's own --help with more detail and example. Thanks for following up on this.


commit: Updates the definition of an existing module.
Arguments:
--source: (Optional) Specifies the source directory for modules (defaults to the current working directory).
Parameters:
<module1> <module2>: Names of the modules to update (required).
Example: cb commit module1

create: Creates a new module of a specific type.
Arguments:
--target: (Optional) Specifies the target directory for creating the module (defaults to the modules directory within the git root).
Parameters:
--name <name>: Name for the new module (required).
--type <type>: Type of module to create (e.g., react-native) (required).
Example: cb create --name myModule --type react-native

init: Initializes a new blank modules repository.
Arguments:
--name <project-name>: Specifies the name of the new project directory to create.
Example: cb init --name my-modules

login: Logs in to your Crowdbotics account.
Example: cb login

logout: Logs out of your Crowdbotics account.
Example: cb logout

modules: Manages modules for your organization.
Arguments:
--search: (Optional) Searches for modules by name or description.
--visibility: (Optional) Filters modules by visibility (private or public).
--status: (Optional) Filters modules by status (published or archived).
--page: (Optional) Specifies the page number for paginated results.
--unarchive: (Optional) Flag to unarchive an archived module.
Parameters:
list: Lists available modules (optional subcommand).
get <id>: Gets details for a specific module by its ID (required subcommand with parameter).
archive <id>: Archives a specific module by its ID (required subcommand with parameter).
help: Shows help for the modules command (optional subcommand).
Example:
Copy link
Author

@CrowdboticsDocs CrowdboticsDocs Apr 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we either need to remove this or generate some real examples here. there are a lot of arguments and parameters here.


parse: Parses and validates module definitions.
Arguments:
--source: (Optional) Specifies the source directory for the module definition file.
--write: (Optional) Specifies the output file path to write the parsed data.
Parameters:
<--source> (required if no argument is provided) or <file>: Path to the module definition file.
Example: cb parse --source ./modules

publish: Publishes your modules to your organization's private catalog. When run, this command prompts for more information.
Example: cb publish

remove: Removes one or more modules from your Demo app.
Arguments:
--source: (Optional) Specifies the source directory for modules (defaults to the Crowdbotics modules directory based on package location).
--project: (Optional) Specifies the project directory to remove modules from (defaults to the git root of the current working directory).
Parameters:
<module1> <module2>: Names of the modules to remove (required).
Example: cb remove module1 module2

upgrade: Upgrades your existing app's scaffold to the latest version or a specific version.
Arguments:
--version: (Optional) Specifies the version to upgrade to.
Example: cb upgrade --version 2.3.0
`);
}
};
Expand Down