From 7730fd974427ac7345baf518839bbe092da2f48a Mon Sep 17 00:00:00 2001 From: Jeremy Friesen Date: Fri, 28 Feb 2020 10:47:00 -0500 Subject: [PATCH] Tweaking documentation I spent some time reading the yardoc output to hopefully better convey the intention and usage of this small bit of code. I also wanted to document how to generate local documentation, as that might be something somewhat opaque in a long-lived community. ~enhancement --- README.md | 14 ++++++++++++++ lib/huborg.rb | 43 +++++++++++++++++++++++++++++++++---------- lib/huborg/version.rb | 2 ++ 3 files changed, 49 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index c056054..11da488 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,20 @@ $ export GITHUB_ORG_NAME=their-organization $ bundle exec rake test:push_template ``` +## Documentation + +The product owner encourages you to clone this repository and generate the +documentation. + +- [ ] `git clone https://github.com/samvera-labs/huborg` +- [ ] `cd huborg` +- [ ] `git checkout master && git pull --rebase` +- [ ] `gem install yard` +- [ ] `yard` + +The above process will generate documentation in `./doc`. Open `./doc/index.html` +in your browser. (On OSX, try `open ./doc/index.html`). + # Acknowledgments This software has been developed by and is brought to you by the Samvera community. Learn more at the diff --git a/lib/huborg.rb b/lib/huborg.rb index 877d387..14e5f62 100644 --- a/lib/huborg.rb +++ b/lib/huborg.rb @@ -4,7 +4,10 @@ require 'fileutils' require 'set' +# A module for interacting with Github organizations module Huborg + # If there's a problem with Huborg, expect to see this error OR an + # error from an underlying library. class Error < RuntimeError; end # The class that interacts with organizational repositories. @@ -15,19 +18,38 @@ class Error < RuntimeError; end # * {#synchronize_mailmap!} - ensure all git .mailmap files are # synchronized class Client - # Match all repositories + # When checking repository names, this pattern will match all repositories. + # @see #initialize `#initialize` for details on the repository pattern. DEFAULT_REPOSITORY_PATTERN = %r{\A.*\Z} + # @since v0.1.0 + # # @param logger [Logger] used in logging output of processes # @param github_access_token [String] used to connect to the Oktokit::Client. # The given token will need to have permission to interact with # repositories. Defaults to ENV["GITHUB_ACCESS_TOKEN"] - # @param org_names [Array] used as the default list of Github organizations + # @param org_names [Array, String] used as the default list of Github organizations # in which we'll interact. # @param repository_pattern [Regexp] limit the list of repositories to the given pattern; defaults to ALL # - # @see https://github.com/octokit/octokit.rb#oauth-access-tokens for OAuth Tokens - # @see https://developer.github.com/v3/repos/#list-organization-repositories for repository data structures + # @example + # # Without configuration options. You'll want ENV["GITHUB_ACCESS_TOKEN"] + # # to be assigned. + # client = Huborg::Client.new(org_names: ["samvera", "samvera-labs"]) + # + # # With explicit configuration options. Note, we'll be interacting only + # # with repositories that contain the case-insensitive word "hyrax" (case- + # # insensitivity is declared as the `i` at the end of the regular + # # expression). + # client = Huborg::Client.new( + # logger: Logger.new(STDOUT), + # github_access_token: "40-random-characters-for-your-token", + # org_names: ["samvera", "samvera-labs"], + # repository_patter: %r{hyrax}i + # ) + # + # @see https://github.com/octokit/octokit.rb#oauth-access-tokens Octokit's documentation for OAuth Tokens + # @see https://developer.github.com/v3/repos/#list-organization-repositories Github's documentation for repository data structures def initialize(logger: default_logger, github_access_token: default_access_token, org_names:, repository_pattern: DEFAULT_REPOSITORY_PATTERN) @logger = logger @client = Octokit::Client.new(access_token: github_access_token) @@ -55,6 +77,7 @@ def default_access_token public # @api public + # @since v0.1.0 # # Responsible for pushing the given template file to all of the # organizations repositories. As we are pushing changes to @@ -104,7 +127,7 @@ def push_template!(template:, filename:, overwrite: false) # the :key of a license object in Github's API (see # https://api.github.com/licenses) # - # @see https://api.github.com/licenses for a list of license keys + # @see https://api.github.com/licenses Github's documentation for a list of license keys # @return [True] the task completed without exception (there may be # logged errors) def audit_license(skip_private: true, skip_archived: true, allowed_licenses: :all) @@ -140,8 +163,8 @@ def audit_license(skip_private: true, skip_archived: true, allowed_licenses: :al # changes, this file will be pushed to all non-archived # repositories # @return [True] if successfully completed - # @see https://www.git-scm.com/docs/git-check-mailmap for more on - # git's .mailmap file + # @see https://www.git-scm.com/docs/git-check-mailmap Git's documentation + # for more on git's .mailmap file # @todo Ensure that this doesn't create a pull request if nothing # has changed. def synchronize_mailmap!(template:, consolidated_template: template) @@ -255,8 +278,8 @@ def each_github_repository(&block) end # @note Due to an implementation detail in octokit.rb, refs sometimes - # need to be "heads/master" and "refs/heads/master" as detailed - # below + # need to be "heads/master" and "refs/heads/master" as detailed + # below # @param repo [#full_name, #archived] Likely the result of Octokit::Client#org # @param template [String] name of the template to push out to all # repositories @@ -352,7 +375,7 @@ def clone_and_rebase_one!(repo:, directory:, skip_dirty: true, force: false, sha # given org # @param org [Object] An Organization object (provided by Oktokit # object) from which this method fetchs the related :rel - + # # @return [Array] def fetch_rel_for(rel:, org:) # Build a list of repositories, note per Github's API, these are diff --git a/lib/huborg/version.rb b/lib/huborg/version.rb index 4e4de68..50274b1 100644 --- a/lib/huborg/version.rb +++ b/lib/huborg/version.rb @@ -1,3 +1,5 @@ module Huborg + # The current version of Huborg, as per Semantic Versioning + # @see https://semver.org VERSION = "0.1.0" end