From 9228175d347b3503b258be07f451405100da7905 Mon Sep 17 00:00:00 2001 From: Marc Siegel Date: Mon, 11 Mar 2024 10:19:08 -0400 Subject: [PATCH] Fix yard server reload In addition to adding missing gem 'webrick': - Switch to BUNDLE_WITH from BUNDLE_WITHOUT - Improve README w.r.t. Documentation generation --- .github/workflows/main.yml | 4 ++-- CHANGELOG.md | 8 +++++--- Gemfile | 5 +++-- Gemfile.lock | 2 ++ README.md | 41 +++++++++++++++++++++++++++++--------- 5 files changed, 44 insertions(+), 16 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index dacd28f..6c13c04 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -23,8 +23,8 @@ jobs: # * https://github.com/ruby/setup-ruby#bundle-config - name: Set bundler environment variables run: | - echo "BUNDLE_WITHOUT=checks:docs" >> $GITHUB_ENV - if: matrix.ruby != 3.2 + echo "BUNDLE_WITH=checks:docs" >> $GITHUB_ENV + if: matrix.ruby == 3.2 # Use 'bundler-cache: true' instead of actions/cache as advised: # * https://github.com/actions/cache/blob/main/examples.md#ruby---bundler diff --git a/CHANGELOG.md b/CHANGELOG.md index 100a5a7..40b5e5e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,14 +7,16 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ## [Unreleased](https://github.com/panorama-ed/memo_wise/compare/v1.8.0...HEAD) -**Gem enhancements:** none +**Gem enhancements:** + +- Fixed a bug that overwrote existing self.extended method definitions. [[#324]](https://github.com/panorama-ed/memo_wise/pull/314) +- Fixed a bug that overwrote existing self.inherited method definitions. [[#325]](https://github.com/panorama-ed/memo_wise/pull/315) _No breaking changes!_ **Project enhancements:** -- Fixed a bug that overwrote existing self.extended method definitions. [[#324]](https://github.com/panorama-ed/memo_wise/pull/314) -- Fixed a bug that overwrote existing self.inherited method definitions. [[#325]](https://github.com/panorama-ed/memo_wise/pull/315) +- Fixed `bundle exec yard server --reload` and related documentation [[#333]](https://github.com/panorama-ed/memo_wise/pull/333) ## [v1.8.0](https://github.com/panorama-ed/memo_wise/compare/v1.7.0...v1.8.0) - 2023-10-25 diff --git a/Gemfile b/Gemfile index 8ef452b..65957f5 100644 --- a/Gemfile +++ b/Gemfile @@ -12,7 +12,7 @@ group :test do end # Excluded from CI except on latest MRI Ruby, to reduce compatibility burden -group :checks do +group :checks, optional: true do gem "panolint-ruby", github: "panorama-ed/panolint-ruby", branch: "main" # Simplecov to generate coverage info @@ -23,9 +23,10 @@ group :checks do end # Excluded from CI except on latest MRI Ruby, to reduce compatibility burden -group :docs do +group :docs, optional: true do gem "dokaz", "~> 0.0.5" gem "redcarpet", "~> 3.6" + gem "webrick", "~> 1.8" gem "yard", "~> 0.9" gem "yard-doctest", "~> 0.1" end diff --git a/Gemfile.lock b/Gemfile.lock index 41f706e..1f1e12d 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -84,6 +84,7 @@ GEM slop (3.6.0) unicode-display_width (2.4.2) values (1.8.0) + webrick (1.8.1) yard (0.9.36) yard-doctest (0.1.17) minitest @@ -102,6 +103,7 @@ DEPENDENCIES simplecov simplecov-cobertura values (~> 1) + webrick (~> 1.8) yard (~> 0.9) yard-doctest (~> 0.1) diff --git a/README.md b/README.md index 70e86bd..ccbabd3 100644 --- a/README.md +++ b/README.md @@ -176,18 +176,42 @@ versions: ## Documentation -### Documentation is Automatically Generated +### Automatically Generated Docs We maintain API documentation using [YARD](https://yardoc.org/), which is published automatically at -[RubyDoc.info](https://rubydoc.info/gems/memo_wise). To -edit documentation locally and see it rendered in your browser, run: +[RubyDoc.info](https://rubydoc.info/gems/memo_wise). + +To generate documentation locally or run documentation tests, +first install the `docs` dependencies (e.g. `yard`) as follows: ```bash -bundle exec yard server +BUNDLE_WITH=docs bundle install ``` -### Documentation Examples are Automatically Tested +### Hot Reloading Docs Locally + +To edit documentation locally and see it rendered in your browser +using hot reloading, run: + +```bash +bundle exec yard server --reload +``` + +You can then open your web browser to `http://127.0.0.1:8808/`. As you +edit documentation locally, reload your browser to see it generated. + +### Static Generate Docs Locally + +To statically generate documentation locally, run: + +```bash +bundle exec yard +``` + +You can then open the generated documentation at `docs/index.html`. + +### Test all Docs Examples We use [yard-doctest](https://github.com/p0deje/yard-doctest) to test all code examples in our YARD documentation. To run `doctest` locally: @@ -204,7 +228,7 @@ locally: bundle exec dokaz ``` -### A Note on Testing +## A Note on Testing When testing memoized *module* methods, note that some testing setups will reuse the same instance (which `include`s/`extend`s/`prepend`s the module) @@ -254,12 +278,11 @@ the [code of conduct](https://github.com/panorama-ed/memo_wise/blob/main/CODE_OF ## Releasing To make a new release of `MemoWise` to -[RubyGems](https://rubygems.org/gems/memo_wise), first install the release +[RubyGems](https://rubygems.org/gems/memo_wise), first install the `release` dependencies (e.g. `rake`) as follows: ```shell -bundle config --local with 'release' -bundle install +BUNDLE_WITH=release bundle install ``` Then carry out these steps: