Use in-code documentation for CLI documentation in README.md

.github/workflows/ci.yml

@@ -51,3 +51,15 @@ jobs:
           ruby-version: head
       - name: Run style checks
         run: bundle exec rubocop
+  documentation:
+    runs-on: ubuntu-latest
+    name: CLI Documentation
+    steps:
+      - uses: actions/checkout@8230315d06ad95c617244d2f265d237a1682d445
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@eae47962baca661befdfd24e4d6c34ade04858f7
+        with:
+          bundler-cache: true
+          ruby-version: head
+      - name: Check autogenerated documentation
+        run: ruby docs/verify_docs.rb

Gemfile.lock

@@ -17,7 +17,7 @@ GIT
 PATH
   remote: .
   specs:
-    use_packs (0.0.15)
+    use_packs (0.0.16)
       code_ownership
       colorize
       packs
@@ -53,7 +53,7 @@ GEM
       smart_properties
     builder (3.2.4)
     byebug (11.1.3)
-    code_ownership (1.32.13)
+    code_ownership (1.32.15)
       code_teams (~> 1.0)
       packs
       sorbet-runtime
@@ -230,4 +230,4 @@ DEPENDENCIES
   use_packs!
 
 BUNDLED WITH
-   2.2.29
+   2.2.33

README.md

@@ -5,47 +5,88 @@ UsePacks is a gem that helps in creating and maintaining packs. It exists to hel
 ## Usage
 Make sure to run `bundle binstub use_packs` to generate `bin/packs` within your application.
 
-### General Help
-`bin/packs --help` or just `bin/packs` to enter interactive mode.
+## CLI Documentation
+## Describe available commands or one specific command
+`bin/packs help [COMMAND]`
 
-### Pack Creation
-`bin/packs create packs/your_pack_name_here`
+## Create pack with name packs/your_pack
+`bin/packs create packs/your_pack`
 
-### Moving files to packs
-`bin/packs move packs/your_pack_name_here path/to/file.rb path/to/directory`
-This is used for moving files into a pack (the pack must already exist).
-Note this works for moving files to packs from the monolith or from other packs
+## Add packs/to_pack to packs/from_pack/package.yml list of dependencies
+`bin/packs add_dependency packs/from_pack packs/to_pack`
 
-Make sure there are no spaces between the comma-separated list of paths of directories.
+Use this to add a dependency between packs.
 
-### Moving a file to public API
-`bin/packs make_public path/to/file.rb,path/to/directory`
-This moves a file or directory to public API (that is -- the `app/public` folder).
+When you use bin/packs add_dependency packs/from_pack packs/to_pack, this command will
+modify packs/from_pack/package.yml's list of dependencies and add packs/to_pack.
 
-Make sure there are no spaces between the comma-separated list of paths of directories.
+This command will also sort the list and make it unique.
+
+## List the top dependency violations of packs/your_pack
+`bin/packs list_top_dependency_violations packs/your_pack`
+
+Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way
+
+You can use this command to list the top dependency violations.
+
+If no pack name is passed in, this will list out violations across all packs.
+
+## List the top privacy violations of packs/your_pack
+`bin/packs list_top_privacy_violations packs/your_pack`
 
-### Listing top privacy violations
-`bin/packs list_top_privacy_violations packs/my_pack`
 Want to create interfaces? Not sure how your pack's code is being used?
 
 You can use this command to list the top privacy violations.
 
 If no pack name is passed in, this will list out violations across all packs.
 
-### Listing top dependency violations
-`bin/packs list_top_dependency_violations packs/my_pack`
-Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way
+## Make files or directories public API
+`bin/packs make_public path/to/file.rb path/to/directory`
 
-You can use this command to list the top dependency violations.
+This moves a file or directory to public API (that is -- the `app/public` folder).
 
-If no pack name is passed in, this will list out violations across all packs.
+Make sure there are no spaces between the comma-separated list of paths of directories.
+
+## Move files or directories from one pack to another
+`bin/packs move packs/destination_pack path/to/file.rb path/to/directory`
+
+This is used for moving files into a pack (the pack must already exist).
+Note this works for moving files to packs from the monolith or from other packs
+
+Make sure there are no spaces between the comma-separated list of paths of directories.
+
+## Lint `package_todo.yml` files to check for formatting issues
+`bin/packs lint_package_todo_yml_files`
+
+## Lint `package.yml` files
+`bin/packs lint_package_yml_files [ packs/my_pack packs/my_other_pack ]`
+
+## Run bin/packwerk validate (detects cycles)
+`bin/packs validate`
+
+## Run bin/packwerk check
+`bin/packs check [ packs/my_pack ]`
+
+## Run bin/packwerk update-todo
+`bin/packs update`
+
+## Regenerate packs/*/package_rubocop_todo.yml for one or more packs
+`bin/packs regenerate_rubocop_todo [ packs/my_pack packs/my_other_pack ]`
+
+## Get info about size and violations for packs
+`bin/packs get_info [ packs/my_pack packs/my_other_pack ]`
+
+## Visualize packs
+`bin/packs visualize [ packs/my_pack packs/my_other_pack ]`
+
+## Rename a pack
+`bin/packs rename`
 
-### Adding a dependency
-`bin/packs add_dependency packs/my_pack packs/dependency_pack_name`
+## Set packs/child_pack as a child of packs/parent_pack
+`bin/packs move_to_parent packs/child_pack packs/parent_pack `
 
-This can be used to quickly modify a `package.yml` file and add a dependency. It also cleans up the list of dependencies to sort the list and remove redundant entries.
 
-### Releasing
+## Releasing
 Releases happen automatically through github actions once a version update is committed to `main`.
 
 ## Discussions, Issues, Questions, and More

docs/verify_docs.rb

@@ -0,0 +1,41 @@
+# typed: strict
+
+require 'bundler/inline'
+
+# Send is to ward off Sorbet which can't type this method invocation
+send(:gemfile) do
+  send(:source, 'https://rubygems.org')
+  gem 'use_packs', path: '../'
+end
+
+all_docs = []
+UsePacks::CLI.all_commands.each do |_command_name, command|
+  all_docs << <<~DOCUMENTATION
+    ## #{command.description}
+    `bin/packs #{command.usage}`
+
+  DOCUMENTATION
+
+  if command.long_description
+    all_docs << command.long_description
+    all_docs << "\n"
+  end
+end
+
+new_autogenerated_content = <<~MARKDOWN.chomp
+  ## CLI Documentation
+  #{all_docs.join}
+  ## Releasing
+MARKDOWN
+
+readme = Pathname.new('README.md')
+new_content = readme.read.gsub(/## CLI Documentation.*?## Releasing/m, new_autogenerated_content)
+
+if ENV['OVERWRITE']
+  readme.write(new_content)
+elsif readme.read == new_content
+  exit 0
+else
+  puts 'README.md is out of date. Use OVERWRITE=1 ruby docs/verify_docs.rb'
+  exit 1
+end

lib/use_packs/cli.rb

@@ -30,6 +30,13 @@ def add_dependency(from_pack, to_pack)
     end
 
     desc 'list_top_dependency_violations packs/your_pack', 'List the top dependency violations of packs/your_pack'
+    long_desc <<~LONG_DESC
+      Want to see who is depending on you? Not sure how your pack's code is being used in an unstated way
+
+      You can use this command to list the top dependency violations.
+
+      If no pack name is passed in, this will list out violations across all packs.
+    LONG_DESC
     option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze'
     sig { params(pack_name: String).void }
     def list_top_dependency_violations(pack_name)
@@ -40,6 +47,13 @@ def list_top_dependency_violations(pack_name)
     end
 
     desc 'list_top_privacy_violations packs/your_pack', 'List the top privacy violations of packs/your_pack'
+    long_desc <<~LONG_DESC
+      Want to create interfaces? Not sure how your pack's code is being used?
+
+      You can use this command to list the top privacy violations.
+
+      If no pack name is passed in, this will list out violations across all packs.
+    LONG_DESC
     option :limit, type: :numeric, default: 10, aliases: :l, banner: 'Specify the limit of constants to analyze'
     sig { params(pack_name: String).void }
     def list_top_privacy_violations(pack_name)
@@ -49,7 +63,12 @@ def list_top_privacy_violations(pack_name)
       )
     end
 
-    desc 'make_public path/to/file.rb path/to/directory', 'Pass in a space-separated list of file or directory paths to make public'
+    desc 'make_public path/to/file.rb path/to/directory', 'Make files or directories public API'
+    long_desc <<~LONG_DESC
+      This moves a file or directory to public API (that is -- the `app/public` folder).
+
+      Make sure there are no spaces between the comma-separated list of paths of directories.
+    LONG_DESC
     sig { params(paths: String).void }
     def make_public(*paths)
       UsePacks.make_public!(
@@ -58,7 +77,13 @@ def make_public(*paths)
       )
     end
 
-    desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Pass in a destination pack and a space-separated list of file or directory paths to move to the destination pack'
+    desc 'move packs/destination_pack path/to/file.rb path/to/directory', 'Move files or directories from one pack to another'
+    long_desc <<~LONG_DESC
+      This is used for moving files into a pack (the pack must already exist).
+      Note this works for moving files to packs from the monolith or from other packs
+
+      Make sure there are no spaces between the comma-separated list of paths of directories.
+    LONG_DESC
     sig { params(pack_name: String, paths: String).void }
     def move(pack_name, *paths)
       UsePacks.move_to_pack!(
@@ -68,7 +93,7 @@ def move(pack_name, *paths)
       )
     end
 
-    desc 'lint_package_todo_yml_files', 'Ensures `package_todo.yml` files are up to date'
+    desc 'lint_package_todo_yml_files', 'Lint `package_todo.yml` files to check for formatting issues'
     sig { void }
     def lint_package_todo_yml_files
       UsePacks.lint_package_todo_yml_files!
@@ -122,7 +147,7 @@ def rename
       puts Private.rename_pack
     end
 
-    desc 'move_to_parent packs/child_pack packs/parent_pack ', 'Sets packs/child_pack as a child of packs/parent_pack'
+    desc 'move_to_parent packs/child_pack packs/parent_pack ', 'Set packs/child_pack as a child of packs/parent_pack'
     sig { params(child_pack_name: String, parent_pack_name: String).void }
     def move_to_parent(child_pack_name, parent_pack_name)
       UsePacks.move_to_parent!(

use_packs.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = 'use_packs'
-  spec.version       = '0.0.15'
+  spec.version       = '0.0.16'
   spec.authors       = ['Gusto Engineers']
   spec.email         = ['dev@gusto.com']