Add source-host support for GitLab and Bitbucket

GitHub as default, back-compatible.

Use extensions for assets to avoid duplication and shipping
unneeded files.

Author: johnfairh

CHANGELOG.md

@@ -9,9 +9,18 @@
 * Support DocC-style autolinks and callouts in markdown.  
   [John Fairhurst](https://github.com/johnfairh)
 
+* Add `--source-host` option to support projects hosted on GitLab and
+  Bitbucket as well as GitHub.  Options `--source-host-url` and
+  `--source-host-files-url` and new Mustache tags replace the 'github' versions
+  which remain as back-compatibility aliases.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#314](https://github.com/realm/jazzy/issues/314)
+
 ##### Bug Fixes
 
-* None.
+* Fix source-host line number references in Swift symbolgraph mode, and
+  in ObjC mode for references to one-line declarations.  
+  [John Fairhurst](https://github.com/johnfairh)
 
 ## 0.13.7
 

README.md

@@ -117,8 +117,9 @@ jazzy \
   --clean \
   --author Realm \
   --author_url https://realm.io \
-  --github_url https://github.com/realm/realm-cocoa \
-  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
+  --source-host github \
+  --source-host-url https://github.com/realm/realm-cocoa \
+  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v0.96.2 \
   --module-version 0.96.2 \
   --build-tool-arguments -scheme,RealmSwift \
   --module RealmSwift \
@@ -159,8 +160,9 @@ jazzy \
   --clean \
   --author Realm \
   --author_url https://realm.io \
-  --github_url https://github.com/realm/realm-cocoa \
-  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v2.2.0 \
+  --source-host github \
+  --source-host-url https://github.com/realm/realm-cocoa \
+  --source-host-files-url https://github.com/realm/realm-cocoa/tree/v2.2.0 \
   --module-version 2.2.0 \
   --build-tool-arguments --objc,Realm/Realm.h,--,-x,objective-c,-isysroot,$(xcrun --show-sdk-path),-I,$(pwd) \
   --module Realm \
@@ -176,8 +178,9 @@ jazzy \
   --objc \
   --author AFNetworking \
   --author_url http://afnetworking.com \
-  --github_url https://github.com/AFNetworking/AFNetworking \
-  --github-file-prefix https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
+  --source-host github \
+  --source-host-url https://github.com/AFNetworking/AFNetworking \
+  --source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
   --module-version 2.6.2 \
   --umbrella-header AFNetworking/AFNetworking.h \
   --framework-root . \

lib/jazzy/config.rb

@@ -325,16 +325,42 @@ def hide_objc?
                    'e.g. https://realm.io/docsets/realm.xml)',
       parse: ->(d) { URI(d) }
 
-    config_attr :github_url,
-      command_line: ['-g', '--github_url URL'],
-      description: 'GitHub URL of this project (e.g. '\
-                   'https://github.com/realm/realm-cocoa)',
+    SOURCE_HOSTS = %w[github gitlab bitbucket].freeze
+
+    config_attr :source_host,
+      command_line: "--source-host #{SOURCE_HOSTS.join(' | ')}",
+      description: ['The source-code hosting site to be linked from documentation.',
+                    'This setting affects the logo image and link format.',
+                    "Default: 'github'"],
+      default: 'github',
+      parse: ->(host) do
+        return host.to_sym if SOURCE_HOSTS.include?(host)
+
+        raise "Unsupported source_host '#{host}', "\
+          "supported values: #{SOURCE_HOSTS.join(', ')}"
+      end
+
+    config_attr :source_host_url,
+      command_line: ['--source-host-url URL'],
+      description: ["URL to link from the source host's logo.",
+                    'For example https://github.com/realm/realm-cocoa'],
       parse: ->(g) { URI(g) }
 
-    config_attr :github_file_prefix,
+    alias_config_attr :github_url, :source_host_url,
+      command_line: ['-g', '--github_url URL'],
+      description: 'Back-compatibility alias for source_host_url.'
+
+    config_attr :source_host_files_url,
+      command_line: '--source-host-files-url PREFIX',
+      description: [
+        "The base URL on the source host of the project's files, to link "\
+          'from individual declarations.',
+        'For example https://github.com/realm/realm-cocoa/tree/v0.87.1',
+      ]
+
+    alias_config_attr :github_file_prefix, :source_host_files_url,
       command_line: '--github-file-prefix PREFIX',
-      description: 'GitHub URL file prefix of this project (e.g. '\
-                   'https://github.com/realm/realm-cocoa/tree/v0.87.1)'
+      description: 'Back-compatibility alias for source_host_files_url'
 
     config_attr :docset_playground_url,
       command_line: '--docset-playground-url URL',
@@ -476,9 +502,15 @@ def self.parse!
         )
       end
 
+      config.validate
+
       config
     end
 
+    def warning(message)
+      warn "WARNING: #{message}"
+    end
+
     # rubocop:disable Metrics/MethodLength
     def parse_command_line
       OptionParser.new do |opt|
@@ -510,6 +542,10 @@ def parse_command_line
           exit
         end
       end.parse!
+
+      unless ARGV.empty?
+        warning "Leftover unused command-line text: #{ARGV}"
+      end
     end
 
     def parse_config_file
@@ -527,12 +563,12 @@ def parse_config_file
 
       config_file.each do |key, value|
         unless attr = attrs_by_conf_key[key]
-          message = "WARNING: Unknown config file attribute #{key.inspect}"
+          message = "Unknown config file attribute #{key.inspect}"
           if matching_name = attrs_by_name[key]
             message +=
               " (Did you mean #{matching_name.first.config_file_key.inspect}?)"
           end
-          warn message
+          warning message
           next
         end
 
@@ -541,6 +577,16 @@ def parse_config_file
 
       self.base_path = nil
     end
+
+    def validate
+      if source_host_configured &&
+         source_host_url.nil? &&
+         source_host_files_url.nil?
+        warning 'Option `source_host` is set but has no effect without either '\
+          '`source_host_url` or `source_host_files_url`.'
+      end
+    end
+
     # rubocop:enable Metrics/MethodLength
 
     def locate_config_file

lib/jazzy/doc_builder.rb

@@ -134,7 +134,7 @@ def self.build_site(docs, coverage, options)
         SearchBuilder.build(source_module, output_dir)
       end
 
-      copy_extensions(output_dir)
+      copy_extensions(source_module, output_dir)
       copy_theme_assets(output_dir)
 
       DocsetBuilder.new(output_dir, source_module).build!
@@ -219,7 +219,10 @@ def self.copy_theme_assets(destination)
       end
     end
 
-    def self.copy_extensions(destination)
+    def self.copy_extensions(source_module, destination)
+      if source_host = source_module.host&.extension
+        copy_extension(source_host, destination)
+      end
       copy_extension('katex', destination) if Markdown.has_math
     end
 
@@ -251,7 +254,14 @@ def self.document_markdown(source_module, doc_model, path_to_root)
       doc[:structure] = source_module.doc_structure
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url
+      if source_host = source_module.host
+        doc[:source_host_name] = source_host.name
+        doc[:source_host_url] = source_host.url
+        doc[:source_host_image] = source_host.image
+        doc[:source_host_item_url] = source_host.item_url(doc_model)
+        doc[:github_url] = doc[:source_host_url]
+        doc[:github_token_url] = doc[:source_host_item_url]
+      end
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:hide_name] = true
@@ -326,39 +336,14 @@ def self.generate_badge(coverage, options)
     end
     # rubocop:enable Metrics/MethodLength
 
-    def self.should_link_to_github(file)
-      return unless file
-
-      file = file.realpath.to_path
-      source_directory = Config.instance.source_directory.to_path
-      file.start_with?(source_directory)
-    end
-
-    # Construct Github token URL
-    # @param [Hash] item Parsed doc child item
-    # @param [Config] options Build options
-    def self.gh_token_url(item, source_module)
-      return unless github_prefix = source_module.github_file_prefix
-      return unless should_link_to_github(item.file)
-
-      gh_line = if item.start_line && (item.start_line != item.end_line)
-                  "#L#{item.start_line}-L#{item.end_line}"
-                else
-                  "#L#{item.line}"
-                end
-      relative_file_path = item.file.realpath.relative_path_from(
-        source_module.root_path,
-      )
-      "#{github_prefix}/#{relative_file_path}#{gh_line}"
-    end
-
     # Build mustache item for a top-level doc
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
     # rubocop:disable Metrics/MethodLength
     def self.render_item(item, source_module)
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
+      source_host_item_url = source_module.host&.item_url(item)
       {
         name: item.name,
         name_html: item.name.gsub(':', ':<wbr>'),
@@ -368,7 +353,8 @@ def self.render_item(item, source_module)
         other_language_declaration: item.display_other_language_declaration,
         usr: item.usr,
         dash_type: item.type.dash_type,
-        github_token_url: gh_token_url(item, source_module),
+        source_host_item_url: source_host_item_url,
+        github_token_url: source_host_item_url,
         default_impl_abstract: item.default_impl_abstract,
         from_protocol_extension: item.from_protocol_extension,
         return: item.return,
@@ -452,8 +438,14 @@ def self.document(source_module, doc_model, path_to_root)
       doc[:tasks] = render_tasks(source_module, doc_model.children)
       doc[:module_name] = source_module.name
       doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url
-      doc[:github_token_url] = gh_token_url(doc_model, source_module)
+      if source_host = source_module.host
+        doc[:source_host_name] = source_host.name
+        doc[:source_host_url] = source_host.url
+        doc[:source_host_image] = source_host.image
+        doc[:source_host_item_url] = source_host.item_url(doc_model)
+        doc[:github_url] = doc[:source_host_url]
+        doc[:github_token_url] = doc[:source_host_item_url]
+      end
       doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:deprecation_message] = doc_model.deprecation_message

lib/jazzy/extensions/bitbucket/img/bitbucket.svg

@@ -64,9 +64,9 @@ def self.apply_config_defaults(podspec, config)
         config.version = podspec.version.to_s
         config.version_configured = true
       end
-      unless config.github_file_prefix_configured
-        config.github_file_prefix = github_file_prefix(podspec)
-        config.github_file_prefix_configured = true
+      unless config.source_host_files_url_configured
+        config.source_host_files_url = github_file_prefix(podspec)
+        config.source_host_files_url_configured = true
       end
       unless config.swift_version_configured
         trunk_swift_build = podspec.attributes_hash['pushed_with_swift_version']