metanorma-cli 1.12.4 → 1.12.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83127d9943ff11c57968eba5da57a1506bab8cdbe1e035e055c382b5a70ba8d9
-  data.tar.gz: 76a08db2cd6f26d9f82a795fd2075eabe1f4ec7b1789bb56d6fccd49deaf188d
+  metadata.gz: 838952cee69c23736d7547e92a620e72a827197a29a30e1ea1836f234ed04d82
+  data.tar.gz: 74374105306969e0ad2ef4cb50463f56a10cafb783e7aeaa9e7c1c833ed593a2
 SHA512:
-  metadata.gz: 3e43bd5b2d5a3cb5bea64d82109963de633ab0c3e139ae36283cf4cbc0756a54e7952157c37e20c2bf0ee1c6edb09245671b77a5b1054a5073d13794063557e0
-  data.tar.gz: ac22976c0ee80b29e48ba6559230c742f97d86bbc2243cd51a4657833dc54ffb6b60b5a9919c8bbfc6be7404e9d6c4593fe8e5028ceb8cd45213d64b6b6f6ed9
+  metadata.gz: 4c0ab5db08eaf4d709d9f20c18e690b7eeab0997bd188122f514b022063a94d58454a6d5b06ae8018564724b35dc43a65862057c2fb83723588bd204b6eb5db4
+  data.tar.gz: 03a01f8b46739e421fb458a05ce48e11970535afc921990489edd3b7f6b4c5a1bcff61f4a3149229040e2718bba608576275d2974081e8036869707896c6dd54

data/lib/metanorma/cli/collection.rb

@@ -3,6 +3,8 @@ require "yaml"
 module Metanorma
   module Cli
     class Collection
+      attr_reader :file, :options
+
       def initialize(file, options)
         @file = file
         @options = Cli.with_indifferent_access(options)
@@ -17,27 +19,26 @@ module Metanorma
       def render
         extract_options_from_file
         collection_file.render(collection_options.compact)
+        self
       end
 
-      private
-
-      attr_reader :file, :options
-
       def collection_file
         @collection_file ||= Metanorma::Collection.parse(file)
       end
 
+      private
+
       def source_folder
-        @source_folder ||= File.dirname(File.expand_path(file))
+        @source_folder ||= Pathname.new(file).realpath.parent
       end
 
       def collection_options
         @collection_options ||= {
           compile: @compile_options,
           output_folder: build_output_folder,
-          coverpage: @options.fetch(:coverpage, nil),
-          format: collection_output_formats(@options.fetch(:format, "")),
-          site_generate: @options["site_generate"],
+          coverpage: options.fetch(:coverpage, nil),
+          format: collection_output_formats(options.fetch(:format, "")),
+          site_generate: options["site_generate"],
         }
       end
 
@@ -45,9 +46,11 @@ module Metanorma
         output_folder = options.fetch(:output_folder, nil)
 
         if output_folder && @output_dir
-          @output_dir.join(output_folder).to_s
+          @output_dir.join(output_folder)
+        elsif output_folder
+          Pathname.new(output_folder)
         else
-          output_folder || source_folder
+          source_folder
         end
       end
 
@@ -60,13 +63,13 @@ module Metanorma
       end
 
       def extract_options_from_file
-        yaml_file = if /\.ya?ml$/.match?(@file.to_s)
-                      YAML.safe_load(File.read(@file.to_s))
-                    elsif /\.xml$/.match?(@file.to_s)
+        yaml_file = if /\.ya?ml$/.match?(file.to_s)
+                      YAML.safe_load(File.read(file.to_s))
+                    elsif /\.xml$/.match?(file.to_s)
                       xml_extract_options_from_file
                     end
 
-        old = options.dup
+        old = @options.dup
         @options = Cli.with_indifferent_access(
           yaml_file.slice("coverpage", "format", "output_folder"),
         )
@@ -74,7 +77,7 @@ module Metanorma
       end
 
       def xml_extract_options_from_file
-        xml = Nokogiri::XML File.read(@file.to_s, encoding: "UTF-8", &:huge)
+        xml = Nokogiri::XML File.read(file.to_s, encoding: "UTF-8", &:huge)
         { "coverpage" => xml.at("//coverpage"),
           "format" => xml.at("//format"),
           "output_folder" => xml.at("//output_folder") }.compact

data/lib/metanorma/cli/commands/site.rb

@@ -10,14 +10,16 @@ module Metanorma
       class Site < ThorWithConfig
         SITE_OUTPUT_DIRNAME = "_site"
 
-        desc "generate [SOURCE_PATH]", "Generate site from collection"
+        desc "generate [SITE_MANIFEST_PATH]", "Generate site from collection"
         option :config,
                aliases: "-c",
-               desc: "Metanorma configuration file"
+               desc: "Metanorma configuration file " \
+                     "(deprecated: use the first argument of " \
+                     "the command instead)"
 
         option :output_dir,
                aliases: "-o",
-               default: Pathname.new(Dir.pwd).join(SITE_OUTPUT_DIRNAME).to_s,
+               default: Pathname.pwd.join(SITE_OUTPUT_DIRNAME).to_s,
                desc: "Output directory for generated site"
 
         option :output_filename_template,
@@ -41,27 +43,97 @@ module Metanorma
 
         option :stylesheet,
                aliases: "-s",
-               desc: "Stylesheet file path for rendering HTML page"
+               desc: "Stylesheet file path " \
+                     "(relative to the current working directory) " \
+                     "for rendering HTML page"
 
         option :template_dir,
                aliases: "-t",
-               desc: "Liquid template directory to render site design"
+               desc: "Liquid template directory " \
+                     "(relative to the current working directory) " \
+                     "to render site design"
 
         option :strict,
                aliases: "-S",
                type: :boolean,
                desc: "Strict compilation: abort if there are any errors"
 
-        def generate(source_path = Dir.pwd)
+        # If no argument is provided, work out the base
+        # path to use for calculation of full paths for
+        # files referenced in the site manifest.
+        #
+        # Additionally, if the config file is not provided,
+        # use the current working directory as the base path.
+        # If the config file is provided, use the directory
+        # of the config file as the base path.
+        #
+        # If the source path is a file and no config file is provided,
+        # treat the source path as the config file.
+        # Similar to the above, use the directory of the config file
+        # as the base path.
+        #
+        # For stylesheet and template_dir options, and if they are
+        # relative paths, they will be resolved relative to whatever
+        # defined them.
+        #
+        # So, if they are provided via the command line,
+        # resolve them relative to the current working directory.
+        # If they are provided via the site manifest,
+        # resolve them relative to the site manifest's directory.
+        def generate(manifest_path = nil)
+          my_options = options.dup # because options is not modifiable
+
+          base_path = calculate_base_path!(my_options, manifest_path).realpath
+
+          calculate_full_paths!(my_options)
+
           Cli::SiteGenerator.generate!(
-            source_path,
-            options,
-            filter_compile_options(options),
+            base_path,
+            my_options,
+            filter_compile_options(my_options),
           )
           UI.say("Site has been generated at #{options[:output_dir]}")
         rescue Cli::Errors::InvalidManifestFileError
           UI.error("Invalid data in: #{options[:config]}")
         end
+
+        private
+
+        # Make relative paths absolute.
+        def calculate_full_paths!(my_options)
+          %i[stylesheet template_dir].each do |key|
+            if my_options[key]
+              path = Pathname.new(my_options[key])
+              if path.relative?
+                my_options[key] = Pathname.pwd.join(path)
+              end
+            end
+          end
+        end
+
+        # Calculate the base path for the site generation.
+        def calculate_base_path!(my_options, manifest_path = nil)
+          config_file = options[:config]
+          if manifest_path.nil?
+            if config_file.nil?
+              # If no config file is given, use the current working directory
+              # as the base path.
+              Pathname.pwd
+            else
+              # If a config file is given, use it as the config file
+              # and use its directory as the base path.
+              Pathname.new(config_file).dirname
+            end
+          elsif File.file?(manifest_path) && config_file.nil?
+            # If a file is given, use it as the config file
+            # and use its directory as the base path.
+            my_options["config"] = manifest_path
+            Pathname.new(manifest_path).dirname
+          else
+            # If directory is given, use it as the base path.
+            Pathname.new(manifest_path)
+          end
+        end
       end
     end
   end

data/lib/metanorma/cli/site_generator.rb

@@ -13,12 +13,12 @@ module Metanorma
       DEFAULT_CONFIG_FILE = "metanorma.yml"
 
       # rubocop:disable Metrics/AbcSize
-      def initialize(source, options = {}, compile_options = {})
+      def initialize(source_path, options = {}, compile_options = {})
         @collection_queue = []
-        @source = find_realpath(source)
-        @site_path = options.fetch(
-          :output_dir, Commands::Site::SITE_OUTPUT_DIRNAME
-        ).to_s
+        @source_path = find_realpath(source_path)
+        @site_path = Pathname.new(
+          options.fetch(:output_dir, Commands::Site::SITE_OUTPUT_DIRNAME),
+        )
 
         @asset_folder = options.fetch(:asset_folder, DEFAULT_ASSET_FOLDER).to_s
         @relaton_collection_index = options.fetch(
@@ -34,11 +34,11 @@ module Metanorma
           template_data("output_filename"),
         )
 
-        # Determine base path for template files
-        # If template_dir is not absolute, then it is relative to the manifest
-        # file.
-        # If manifest file is not provided, then it is relative to the current
-        # directory.
+        # Determine base path for stylesheet & template files
+        # If the file path is relative, it is relative to the directory
+        # containing the site manifest file.
+        # If site manifest file is not provided, then it is relative to the
+        # current directory.
         @base_path = if manifest_file.nil?
                        Pathname.pwd
                      else
@@ -56,85 +56,149 @@ module Metanorma
       def generate!
         ensure_site_asset_directory!
 
+        # compile individual document files
         compile_files!(select_source_files)
 
         site_directory = asset_directory.parent
 
+        # actually compile collection file(s)
+        compile_collections!
+
         Dir.chdir(site_directory) do
           build_collection_file!(relaton_collection_index)
           convert_to_html_page!(relaton_collection_index, DEFAULT_SITE_INDEX)
         end
-
-        dequeue_jobs!
       end
 
       private
 
-      attr_reader :source, :asset_folder, :asset_directory, :site_path,
+      attr_reader :source_path, :asset_folder, :asset_directory, :site_path,
                   :manifest_file, :relaton_collection_index, :stylesheet,
                   :template_dir,
                   :output_filename_template,
                   :base_path
 
-      def find_realpath(source_path)
-        Pathname.new(source_path.to_s).realpath if source_path
+      def find_realpath(path)
+        Pathname.new(path).realpath if path
       rescue Errno::ENOENT
-        source_path
+        path
       end
 
       def default_config
-        default_file = Pathname.new(Dir.pwd).join(DEFAULT_CONFIG_FILE)
+        default_file = Pathname.pwd.join(DEFAULT_CONFIG_FILE)
         default_file if File.exist?(default_file)
       end
 
+      # @return [Array<Pathname>] the list of ADOC source files
+      def select_source_adoc_files
+        select_source_files do |source_path|
+          source_path.glob("**/*.adoc")
+        end
+      end
+
+      # @return [Array<Pathname>] the list of YAML/XML source files
+      def select_source_collection_files
+        select_source_files do |source_path|
+          source_path.glob("**/*.{yaml,yml,xml}")
+        end.select do |f|
+          collection_file?(f)
+        end
+      end
+
+      # Select source files from the manifest if available, otherwise
+      # select all .adoc files in the source directory.
+      # If a block is given, yield the source directory to the block.
+      #
+      # @return [Array<Pathname>] the list of source files
+      # @yieldparam source [Pathname] the source directory
+      # @yieldreturn [Array<Pathname>] the list of source files
+      # @example
+      #  select_source_files do |source|
+      #    source.glob("**/*.adoc")
+      #  end
+      #  # => [#<Pathname:source/1.adoc>, #<Pathname:source/2.adoc>]
+      #
       def select_source_files
         files = source_from_manifest
 
         if files.empty?
-          files = Dir[File.join(source, "**", "*.adoc")]
+          files = if block_given?
+                    yield(source_path)
+                  else
+                    source_path.glob("**/*.adoc")
+                  end
         end
 
         result = files.flatten
         result.uniq!
-        result.reject! { |file| File.directory?(file) }
+        result.reject!(&:directory?)
         result
       end
 
+      # @dependency: files (YAML, XML, RXL) in asset_directory's parent, from
+      # #compile_files! and #compile_collections!
+      #
+      # This looks for collection artifacts from the `collections`
+      # sub-directory, and individual document artifacts from the `documents`
+      # sub-directory.
+      #
+      # @output: documents.xml in site_path
+      #
+      # @param relaton_collection_index_filename [String] the name of the
+      # collection index file (usually documents.xml), but can be changed
+      # through the :collection_name option
       def build_collection_file!(relaton_collection_index_filename)
-        collection_path = [site_path,
-                           relaton_collection_index_filename].join("/")
+        collection_path = site_path.join(relaton_collection_index_filename)
         UI.info("Building collection file: #{collection_path} ...")
 
+        # First concatenate individual document files
+        # But be sure to provide a *relative* path of _site,
+        # that is relative to the manifest file itself?  or relative to PWD!
+        #
+        # It has to be relative to PWD, otherwise the resolved relative paths
+        # will simply not be valid.
+        #
+        # If paths are desired to be relative from the manifest file, then
+        # `RelatonFile.concatenate` needs to accept a base path option, so
+        # `concatenate` can calculate the correct full path to use.
+        #
+        target_path = asset_directory.parent.relative_path_from(Pathname.pwd)
+
         Relaton::Cli::RelatonFile.concatenate(
-          asset_folder,
+          target_path.to_s,
           relaton_collection_index_filename,
           title: manifest[:collection_name],
           organization: manifest[:collection_organization],
         )
       end
 
-      def compile_file!(source)
-        if collection_file?(source)
+      # @dependency: file in file_path, from #select_source_files
+      # @output: file in asset_folder
+      def compile_file!(file_path)
+        if collection_file?(file_path)
+          @collection_queue << file_path
           return
         end
 
-        UI.info("Compiling #{source} ...")
+        UI.info("Compiling #{file_path} ...")
 
         # Incorporate output_filename_template so the output file
         # can be named as desired, using liquid template and Relaton LiquidDrop
         options = @compile_options.merge(
           output_filename_template: output_filename_template,
           format: :asciidoc,
-          output_dir: build_asset_output_directory!(source),
+          output_dir: ensure_site_asset_output_sub_directory!(file_path),
           site_generate: true,
         )
 
-        options[:baseassetpath] = Pathname.new(source.to_s).dirname.to_s
-        Metanorma::Cli::Compiler.compile(source.to_s, options)
+        options[:baseassetpath] = Pathname.new(file_path.to_s).dirname.to_s
+        Metanorma::Cli::Compiler.compile(file_path.to_s, options)
       end
 
+      # @dependency: files in source_path, from #select_source_files
+      # @output: files in asset_folder
       def compile_files!(files)
-        fatals = files.map { |source| compile_file!(source) }
+        fatals = files.map { |file| compile_file!(file) }
         fatals.flatten!
         fatals.compact!
 
@@ -156,9 +220,9 @@ module Metanorma
         end
       end
 
-      def convert_to_html_page!(
-        relaton_index_filename, page_name
-      )
+      # @dependency: documents.xml from #build_collection_file!
+      # @output: index.html in site_path
+      def convert_to_html_page!(relaton_index_filename, page_name)
         UI.info("Generating html site in #{site_path} ...")
 
         Relaton::Cli::XMLConvertor.to_html(
@@ -167,10 +231,7 @@ module Metanorma
           full_path_for(template_dir),
         )
 
-        File.rename(
-          Pathname.new(relaton_index_filename).sub_ext(".html").to_s,
-          page_name,
-        )
+        Pathname.new(relaton_index_filename).sub_ext(".html").rename(page_name)
       end
 
       def template_data(node)
@@ -215,52 +276,83 @@ module Metanorma
       def source_from_manifest
         @source_from_manifest ||= begin
           result = manifest[:files].map do |source_file|
-            file_path = source.join(source_file).to_s
-            file_path.include?("*") ? Dir.glob(file_path) : file_path
+            file_path = source_path.join(source_file)
+            if file_path.to_s.include?("*")
+              source_path.glob(source_file)
+            else
+              file_path
+            end
           end
           result.flatten!
           result
         end
       end
 
+      # Use 'realpath' throughout to ensure consistency with file paths,
+      # especially with temporary directories generated in RSpec.
       def ensure_site_asset_directory!
-        asset_path = [site_path, asset_folder].join("/")
-        @asset_directory = Pathname.new(Dir.pwd).join(asset_path)
-
-        create_directory_if_not_present!(@asset_directory)
-      end
-
-      def create_directory_if_not_present!(directory)
-        FileUtils.mkdir_p(directory) unless directory.exist?
+        asset_path = site_path.join(asset_folder)
+        @asset_directory = Pathname.pwd.join(asset_path)
+        @asset_directory.mkpath
+        @asset_directory = @asset_directory.realpath
+        @asset_directory
       end
 
-      def build_asset_output_directory!(source)
-        sub_directory = Pathname.new(source.gsub(@source.to_s, "")).dirname.to_s
+      # TODO: spec
+      def ensure_site_asset_output_sub_directory!(source)
+        sub_directory = Pathname.new(
+          source.to_s.gsub(@source_path.to_s, ""),
+        ).dirname.to_s
         sub_directory.gsub!("/sources", "")
-        sub_directory.slice!(0)
+        sub_directory.sub!(%r{^/}, "")
 
-        output_directory = asset_directory.join(sub_directory)
-        create_directory_if_not_present!(output_directory)
+        outdir = asset_directory.join(sub_directory)
+        outdir.mkpath
 
-        output_directory
+        outdir
       end
 
+      # @param source [Pathname] the source file
       def collection_file?(source)
-        ext = File.extname(source)&.downcase
-
-        if [".yml", ".yaml"].include?(ext)
-          @collection_queue << source
-        end
+        [".yml", ".yaml", ".xml"].include?(source.extname&.downcase)
       end
 
-      def dequeue_jobs!
-        job = @collection_queue.pop
-
-        if job
+      # Compile each collection file encountered in the site manifest file.
+      #
+      # The collection files are compiled into the `collections` sub-directory
+      # under the asset_directory.  The output folder specified in each of the
+      # collections will be relative to this `collections` folder.
+      #
+      # Putting the files under the asset_directory is important because
+      # the collection files are used to generate the collection index file
+      # and the HTML page.  It is what `Relaton::Cli::RelatonFile.concatenate`
+      # uses to find all artifacts and generate the correct links for them on
+      # the site index.
+      #
+      # Potential conflicts considered:
+      # On the one hand, each individual collection.yml specifies its own
+      # output folder.  This has to be respected.
+      #
+      # On the other hand, the output folders specified in collection.yml files
+      # naturally cannot be expected to live within the `asset_directory`.
+      #
+      # So, for the build_collection_file! method to correctly consider all
+      # generated artifacts, we need to copy the collection files over to the
+      # asset_directory.
+      #
+      # A question you may have: How much does the specific output folder
+      # matter, when doing a site generate?  Since the intent is to generate a
+      # site, the output folder is not really relevant.  The collection files
+      # are copied over to the asset_directory anyway.
+      #
+      # TODO: parallelize the compilation of collection files?
+      #
+      def compile_collections!
+        @collection_queue.compact.each do |file|
           Cli::Collection.render(
-            job,
+            file.to_s,
             compile: @compile_options,
-            output_dir: @asset_directory.join(".."),
+            output_dir: asset_directory,
             site_generate: true,
           )
         end

data/lib/metanorma/cli/version.rb

@@ -1,5 +1,5 @@
 module Metanorma
   module Cli
-    VERSION = "1.12.4".freeze
+    VERSION = "1.12.5".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metanorma-cli
 version: !ruby/object:Gem::Version
-  version: 1.12.4
+  version: 1.12.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: metanorma-ietf