From bec0f33b273c841ea4b92da93fe627f3bf4618f6 Mon Sep 17 00:00:00 2001 From: Richard Michael Date: Fri, 30 Apr 2021 12:52:15 +0200 Subject: [PATCH 1/4] Add and use a singular finder, `find_doc()` --- lib/tasks/docs.thor | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/lib/tasks/docs.thor b/lib/tasks/docs.thor index 0ecd7bdb..786d9ef6 100644 --- a/lib/tasks/docs.thor +++ b/lib/tasks/docs.thor @@ -267,17 +267,19 @@ class DocsCLI < Thor private - def find_docs(names) - names.flat_map do |name| - name, version = name.split(/@|~/) - if version == 'all' - Docs.find(name, false).versions - else - Docs.find(name, version) - end + def find_doc(name) + name, version = name.split(/@|~/) + if version == 'all' + Docs.find(name, false).versions + else + Docs.find(name, version) end end + def find_docs(names) + names.flat_map {|name| find_doc(name)} + end + def find_docs_by_slugs(slugs) slugs.flat_map do |slug| slug, version = slug.split(/~/) From 26a1e61a421f037ff5376c1164e87908eda77a59 Mon Sep 17 00:00:00 2001 From: Richard Michael Date: Fri, 30 Apr 2021 12:53:36 +0200 Subject: [PATCH 2/4] Adjust `docs:generate` version handling - Remove `--version` option - Add `@|~` version notation, consistent with `docs:download` - Adjust `CONTRIBUTING.md` instructions --- .github/CONTRIBUTING.md | 4 ++-- lib/tasks/docs.thor | 5 ++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index a756fd00..26444a3c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -68,9 +68,9 @@ Follow the following steps to update documentations to their latest version: 2. Check if the license is still correct. If you update `options[:attribution]`, also update the documentation's entry in the array in [`assets/javascripts/templates/pages/about_tmpl.coffee`](../assets/javascripts/templates/pages/about_tmpl.coffee) to match. 3. If the documentation has a custom icon, ensure the icons in public/icons/*your_scraper_name*/ are up-to-date. If you pull the updated icon from a place different than the one specified in the `SOURCE` file, make sure to replace the old link with the new one. 4. If `self.links` is defined, check if the urls are still correct. -5. Generate the docs using `thor docs:generate `. +5. Generate the docs using `thor docs:generate `. 6. Make sure `thor docs:generate` doesn't show errors and that the documentation still works well. Verify locally that everything works and that the categorization of entries is still good. Often, updates will require code changes in the scraper or its filters to tweak some new markup in the source website or to categorize new entries. -7. Repeat steps 5 and 6 for all versions that you updated. `thor docs:generate` accepts a `--version` argument to specify which version to scrape. +7. Repeat steps 5 and 6 for all versions that you updated. 8. Create a PR and make sure to fill the checklist in section B of the PR template (remove the other sections). ## Coding conventions diff --git a/lib/tasks/docs.thor b/lib/tasks/docs.thor index 786d9ef6..958da29e 100644 --- a/lib/tasks/docs.thor +++ b/lib/tasks/docs.thor @@ -65,8 +65,7 @@ class DocsCLI < Thor handle_doc_not_found_error(error) end - desc 'generate [--version] [--verbose] [--debug] [--force] [--package]', 'Generate a documentation' - option :version, type: :string + desc 'generate ( | ) [--verbose] [--debug] [--force] [--package]', 'Generate a documentation' option :all, type: :boolean option :verbose, type: :boolean option :debug, type: :boolean @@ -80,7 +79,7 @@ class DocsCLI < Thor require 'unix_utils' if options[:package] - doc = Docs.find(name, options[:version]) + doc = find_doc(name) if doc < Docs::UrlScraper && !options[:force] puts <<-TEXT.strip_heredoc From 21827a6b69d0f16ea43a63b59b4226f3d0f82dc3 Mon Sep 17 00:00:00 2001 From: Richard Michael Date: Fri, 30 Apr 2021 12:54:40 +0200 Subject: [PATCH 3/4] Adjust `docs:page` version handling - Remove `--version` option - Add `@|~` version notation, consistent with other commands --- lib/tasks/docs.thor | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/tasks/docs.thor b/lib/tasks/docs.thor index 958da29e..7ac6f1df 100644 --- a/lib/tasks/docs.thor +++ b/lib/tasks/docs.thor @@ -40,8 +40,7 @@ class DocsCLI < Thor TTY::Pager.new.page(output) end - desc 'page [path] [--version] [--verbose] [--debug]', 'Generate a page (no indexing)' - option :version, type: :string + desc 'page ( | ) [path] [--verbose] [--debug]', 'Generate a page (no indexing)' option :verbose, type: :boolean option :debug, type: :boolean def page(name, path = '') @@ -56,7 +55,8 @@ class DocsCLI < Thor Docs.install_report :filter, :request, :doc end - if Docs.generate_page(name, options[:version], path) + name, version = name.split(/@|~/) + if Docs.generate_page(name, version, path) puts 'Done' else puts "Failed!#{' (try running with --debug for more information)' unless options[:debug]}" From 64bf56e352eeec612726f04fb8c555906d4d49dd Mon Sep 17 00:00:00 2001 From: Richard Michael Date: Fri, 30 Apr 2021 11:38:05 +0200 Subject: [PATCH 4/4] Consistent descriptions --- lib/tasks/docs.thor | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/tasks/docs.thor b/lib/tasks/docs.thor index 7ac6f1df..d63ea170 100644 --- a/lib/tasks/docs.thor +++ b/lib/tasks/docs.thor @@ -118,7 +118,7 @@ class DocsCLI < Thor puts 'Done' end - desc 'download ( ... | --default | --installed | --all)', 'Download documentations' + desc 'download ( ... | --default | --installed | --all)', 'Download documentation packages' option :default, type: :boolean option :installed, type: :boolean option :all, type: :boolean @@ -141,7 +141,7 @@ class DocsCLI < Thor handle_doc_not_found_error(error) end - desc 'package ...', 'Package documentations' + desc 'package ...', 'Create documentation packages' def package(*names) require 'unix_utils' docs = find_docs(names)