asciidoctor-godoc 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 290030c6bab807edcb49c4ccdc07f4baf8ab959185c7d7091ed78703a3fc4c6c
+  data.tar.gz: 3df07c648e51cacc626d765af60fd64f1bb819dc3de9b1b1d679cf11250a522e
+SHA512:
+  metadata.gz: 4c754b83762c25d7416ef08dacaaa299721a1d4b14190c50bd923126d845bb190283bfe8e50a2b9c4499563bfeee8703e29bb597dee44b9d8fabb91b7c00e857
+  data.tar.gz: 9908d887be80089d6a1a7a05a7a5ab2dc000e3e74355c11ea8edfb3da10664c25ca06c9df2ef54def7986512132d18d1a10ad0b406b0fc9e2e168f2498f837bd

data/.rubocop.yml

@@ -0,0 +1,306 @@
+require:
+  - rubocop-rake
+  - rubocop-minitest
+
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Enabled: true
+
+Naming/FileName:
+  Enabled: true
+  Exclude: [ lib/asciidoctor-godoc.rb ]
+
+Gemspec/DeprecatedAttributeAssignment:
+  Enabled: true
+
+Gemspec/RequireMFA:
+  Enabled: true
+
+Layout/LineContinuationLeadingSpace:
+  Enabled: true
+
+Layout/LineContinuationSpacing:
+  Enabled: true
+
+Layout/LineEndStringConcatenationIndentation:
+  Enabled: true
+
+Layout/SpaceBeforeBrackets:
+  Enabled: true
+
+Lint/AmbiguousAssignment:
+  Enabled: true
+
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: true
+
+Lint/AmbiguousRange:
+  Enabled: true
+
+Lint/ConstantOverwrittenInRescue:
+  Enabled: true
+
+Lint/DeprecatedConstants:
+  Enabled: true
+
+Lint/DuplicateBranch:
+  Enabled: true
+
+Lint/DuplicateMagicComment:
+  Enabled: true
+
+Lint/DuplicateRegexpCharacterClassElement:
+  Enabled: true
+
+Lint/EmptyBlock:
+  Enabled: true
+
+Lint/EmptyClass:
+  Enabled: true
+
+Lint/EmptyInPattern:
+  Enabled: true
+
+Lint/IncompatibleIoSelectWithFiberScheduler:
+  Enabled: true
+
+Lint/LambdaWithoutLiteralBlock:
+  Enabled: true
+
+Lint/NoReturnInBeginEndBlocks:
+  Enabled: true
+
+Lint/NonAtomicFileOperation:
+  Enabled: true
+
+Lint/NumberedParameterAssignment:
+  Enabled: true
+
+Lint/OrAssignmentToConstant:
+  Enabled: true
+
+Lint/RedundantDirGlobSort:
+  Enabled: true
+
+Lint/RefinementImportMethods:
+  Enabled: true
+
+Lint/RequireRangeParentheses:
+  Enabled: true
+
+Lint/RequireRelativeSelfPath:
+  Enabled: true
+
+Lint/SymbolConversion:
+  Enabled: true
+
+Lint/ToEnumArguments:
+  Enabled: true
+
+Lint/TripleQuotes:
+  Enabled: true
+
+Lint/UnexpectedBlockArity:
+  Enabled: true
+
+Lint/UnmodifiedReduceAccumulator:
+  Enabled: true
+
+Lint/UselessRuby2Keywords:
+  Enabled: true
+
+Naming/BlockForwarding:
+  Enabled: true
+
+Security/CompoundHash:
+  Enabled: true
+
+Security/IoMethods:
+  Enabled: true
+
+Style/ArgumentsForwarding:
+  Enabled: true
+
+Style/ArrayIntersect:
+  Enabled: true
+
+Style/CollectionCompact:
+  Enabled: true
+
+Style/DocumentDynamicEvalDefinition:
+  Enabled: true
+
+Style/EmptyHeredoc:
+  Enabled: true
+
+Style/EndlessMethod:
+  Enabled: true
+
+Style/EnvHome:
+  Enabled: true
+
+Style/FetchEnvVar:
+  Enabled: true
+
+Style/FileRead:
+  Enabled: true
+
+Style/FileWrite:
+  Enabled: true
+
+Style/HashConversion:
+  Enabled: true
+
+Style/HashExcept:
+  Enabled: true
+
+Style/IfWithBooleanLiteralBranches:
+  Enabled: true
+
+Style/InPatternThen:
+  Enabled: true
+
+Style/MagicCommentFormat:
+  Enabled: true
+
+Style/MapCompactWithConditionalBlock:
+  Enabled: true
+
+Style/MapToHash:
+  Enabled: true
+
+Style/MultilineInPatternThen:
+  Enabled: true
+
+Style/NegatedIfElseCondition:
+  Enabled: true
+
+Style/NestedFileDirname:
+  Enabled: true
+
+Style/NilLambda:
+  Enabled: true
+
+Style/NumberedParameters:
+  Enabled: true
+
+Style/NumberedParametersLimit:
+  Enabled: true
+
+Style/ObjectThen:
+  Enabled: true
+
+Style/OpenStructUse:
+  Enabled: true
+
+Style/OperatorMethodCall:
+  Enabled: true
+
+Style/QuotedSymbols:
+  Enabled: true
+
+Style/RedundantArgument:
+  Enabled: true
+
+Style/RedundantConstantBase:
+  Enabled: true
+
+Style/RedundantEach:
+  Enabled: true
+
+Style/RedundantInitialize:
+  Enabled: true
+
+Style/RedundantSelfAssignmentBranch:
+  Enabled: true
+
+Style/RedundantStringEscape:
+  Enabled: true
+
+Style/SelectByRegexp:
+  Enabled: true
+
+Style/StringChars:
+  Enabled: true
+
+Style/SwapValues:
+  Enabled: true
+
+Minitest/AssertInDelta:
+  Enabled: true
+
+Minitest/AssertKindOf:
+  Enabled: true
+
+Minitest/AssertOutput:
+  Enabled: true
+
+Minitest/AssertPathExists:
+  Enabled: true
+
+Minitest/AssertPredicate:
+  Enabled: true
+
+Minitest/AssertRaisesCompoundBody:
+  Enabled: true
+
+Minitest/AssertRaisesWithRegexpArgument:
+  Enabled: true
+
+Minitest/AssertSilent:
+  Enabled: true
+
+Minitest/AssertWithExpectedArgument:
+  Enabled: true
+
+Minitest/AssertionInLifecycleHook:
+  Enabled: true
+
+Minitest/DuplicateTestRun:
+  Enabled: true
+
+Minitest/EmptyLineBeforeAssertionMethods:
+  Enabled: true
+
+Minitest/LiteralAsActualArgument:
+  Enabled: true
+
+Minitest/MultipleAssertions:
+  Enabled: true
+
+Minitest/RefuteInDelta:
+  Enabled: true
+
+Minitest/RefuteKindOf:
+  Enabled: true
+
+Minitest/RefutePathExists:
+  Enabled: true
+
+Minitest/RefutePredicate:
+  Enabled: true
+
+Minitest/SkipEnsure:
+  Enabled: true
+
+Minitest/SkipWithoutReason:
+  Enabled: true
+
+Minitest/TestMethodName:
+  Enabled: true
+
+Minitest/UnreachableAssertion:
+  Enabled: true
+
+Minitest/UnspecifiedException:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.1.2

data/CHANGELOG.adoc

@@ -0,0 +1,5 @@
+= Changelog
+
+== 0.1.0 - 2022-12-12
+
+* Initial release

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :lint do
+  gem "rubocop", "~> 1.40.0", require: false
+  gem "rubocop-minitest", "~> 0.25.0"
+  gem "rubocop-rake", "~> 0.6.0", require: false
+end
+
+group :test do
+  gem "minitest", "~> 5.16"
+end
+
+gem "rouge", "~> 4.0", group: :docs

data/Gemfile.lock

@@ -0,0 +1,54 @@
+PATH
+  remote: .
+  specs:
+    asciidoctor-godoc (0.1.0)
+      asciidoctor (>= 2.0.0, < 3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    asciidoctor (2.0.18)
+    ast (2.4.2)
+    json (2.6.3)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rouge (4.0.0)
+    rubocop (1.40.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.0)
+      parser (>= 3.1.1.0)
+    rubocop-minitest (0.25.0)
+      rubocop (>= 0.90, < 2.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.3.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  asciidoctor-godoc!
+  minitest (~> 5.16)
+  rake (~> 13.0.0)
+  rouge (~> 4.0)
+  rubocop (~> 1.40.0)
+  rubocop-minitest (~> 0.25.0)
+  rubocop-rake (~> 0.6.0)
+
+BUNDLED WITH
+   2.3.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Abhinav Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.adoc

@@ -0,0 +1,236 @@
+= asciidoctor-godoc
+:toc:
+:url-godoc: https://pkg.go.dev
+
+An asciidoctor extension that adds support for a `godoc` macro.
+The macro allows you to reference types and functions in a Go package by name,
+and links to their documentation on {url-godoc}[pkg.go.dev].
+
+For example, given the following:
+
+.Input
+[,asciidoctor]
+----
+The godoc:http[] package provides
+godoc:net/http#ServeMux[] for request routing.
+Register zero or more godoc:net/http#Handler[handlers] against it,
+and specify it as a godoc:net/http#Server.Handler[]
+in your server's configuration.
+----
+
+.Output
+[%collapsible]
+====
+The {url-godoc}/http[http] package provides
+{url-godoc}/net/http#ServeMux[`http.ServeMux`] for request routing.
+Register zero or more {url-godoc}/net/http#Handler[handlers] against it,
+and specify it as a {url-godoc}/net/http#Server.Handler[`Server.Handler`]
+in your server's configuration.
+====
+
+== Installation
+
+=== With Bundler
+
+To install the extension with bundler,
+add the following to your Gemfile.
+
+.Gemfile
+[,ruby]
+----
+gem 'asciidoctor-godoc'
+----
+
+Then run the following command:
+
+....
+$ bundle install
+....
+
+=== With gem
+
+To install the extension with the gem command,
+run the following:
+
+....
+$ gem install asciidoctor-godoc
+....
+
+== Usage
+
+You may use the extension with the asciidoctor CLI or as a library.
+
+=== CLI
+
+To use with the asciidoctor CLI, request the module with `-r`.
+
+....
+$ asciidoctor -r asciidoctor-godoc mydoc.adoc
+....
+
+=== Library
+
+To use the extension as a library, require `asciidoctor/godoc`.
+This will register the extension with asciidoctor.
+
+.Use via API
+[,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor/godoc'
+
+Asciidoctor.convert_file 'mydoc.adoc'
+----
+
+If you don't want the extension automatically registered,
+import the inline macro implementation manually from
+`asciidoctor/godoc/inline_macro`.
+
+.Use with a scoped registry
+[,ruby]
+----
+require 'asciidoctor/extensions'
+require 'asciidoctor/godoc/inline_macro'
+
+registry = Asciidoctor::Extensions.create
+registry.inline_macro Asciidoctor::Godoc::InlineMacro
+Asciidoctor.convert_file 'mydoc.adoc', extension_registry: registry
+----
+
+== Syntax
+
+The inline macro supports the following formats:
+
+....
+godoc:$importPath[$display] // <1>
+godoc:$importPath#$name[$display] // <2>
+godoc:$importPath#$name.$child[$display] // <3>
+....
+<1> Package reference
+<2> Top-level entity reference
+<3> Entity child reference
+
+Where each of the `$`-variables are:
+
+[horizontal]
+importPath:: full import path of a Go package
+name:: name of a type or function defined in that package
+subname:: name of a method or field if `$name` references a type
+display:: text to display -- leave this empty for a default value
+
+If `$display` is empty, asciidoctor-godoc fills in a default value for it
+based on the format used.
+
+[cols="1a,1a"]
+|====
+| Format | Default `$display`
+
+| `godoc:$importPath[$display]`
+| `$importPath`
+
+| `godoc:$importPath#$name[$display]`
+| `$packageName.$name` footnote:[This isn't always accurate. See <<specify-package-name>>.]
+
+| `godoc:$importPath#$name.$child[$display]`
+| `$name.$child`
+
+|====
+
+NOTE: The default `$display` is an inline literal (`{backtick}...{backtick}`)
+for all forms except the package reference format.
+
+.Examples
+[cols="1a,1a"]
+|====
+| Input | Output
+
+| [,asciidoc]
+----
+Check out the godoc:net/http[] package
+----
+| Check out the {url-godoc}/net/http[net/http] package
+
+| [,asciidoc]
+----
+For more, click godoc:bytes[here].
+----
+| For more, click {url-godoc}/bytes[here].
+
+| [,asciidoc]
+----
+Use godoc:encoding/json#Unmarshal[] to parse JSON.
+----
+| Use {url-godoc}/encoding/json#Unmarshal[`json.Unmarshal`] to parse JSON.
+
+| [,asciidoc]
+----
+Use a godoc:encoding/json#Decoder[decoder] to parse JSON from a stream.
+----
+| Use a {url-godoc}/encoding/json#Decoder[decoder] to parse JSON from a stream.
+
+| [,asciidoc]
+----
+Set godoc:net/http#Server.Handler[] to your preferred handler.
+----
+| Set {url-godoc}/net/http#Server.Handler[`Server.Handler`] to your preferred handler.
+
+| [,asciidoc]
+----
+Pass in the godoc:net/http#Request.Context[request context].
+----
+| Pass in the {url-godoc}/net/http#Request.Context[request context].
+
+|====
+
+[#specify-package-name]
+=== Specifying package names
+
+When using the top-level entity format without display text,
+e.g. `godoc:net/http#ServeMux[]`,
+the extension includes the name of the Go package in the generated text,
+e.g. `http.ServeMux`.
+
+The name of the package is assumed to be the last component of the import path.
+
+[cols="1a,1a"]
+|====
+| Import path | Assumed package name
+
+| `github.com/golang/mock/gomock` | `gomock`
+| `net/http` | `http`
+| `gopkg.in/yaml.v3` | `yaml.v3` (oops!)
+| `example.com/client-go` | `client-go` (oops!)
+
+|====
+
+As evident by the third and fourth cases,
+our guess isn't always correct.
+
+To work around this, the extension supports
+providing import path to package name mappings
+with the `gopkgs` attribute.
+The value of the attribute should be
+a `;`-separated collection of `$importPath = $packageName` mappings.
+
+[,asciidoc]
+----
+= My document
+:gopkgs: gopkg.in/yaml.v3 = yaml; example.com/client-go = client
+----
+
+Split these across multiple lines by escaping newlines:
+
+[,asciidoc]
+----
+= My document
+:gopkgs: gopkg.in/yaml.v3 = yaml; \
+         example.com/client-go = client
+----
+
+For import paths specified in this mapping,
+the extension will prefer the provided package name.
+
+== License
+
+This software is available as open source
+under the terms of the https://opensource.org/licenses/MIT[MIT License].

data/Rakefile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "asciidoctor"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+desc "Generates the GitHub Pages website"
+task :site do
+  Asciidoctor.convert_file "README.adoc",
+                           to_file: "_site/index.html",
+                           standalone: true,
+                           mkdirs: true,
+                           safe: :safe,
+                           attributes: {
+                             "source-highlighter" => "rouge",
+                             "reproducible" => "true"
+                           }
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/asciidoctor/godoc/inline_macro.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+
+module Asciidoctor
+  module Godoc
+    # Provides the 'godoc' inline macro.
+    # This macro allows asciidoc documents to reference
+    # Go packages, types, functions, and methods
+    # with fully-qualified import paths,
+    # and generates links to their reference documentation.
+    class InlineMacro < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :godoc
+      name_positional_attributes "text"
+
+      def pkgmap(attrs)
+        pkgs = attrs["gopkgs"]
+        return {} unless pkgs
+
+        pkgs.split(/\s*;\s*/).to_h { |e| e.split(/\s*=\s*/) }
+      end
+
+      def generate_text(parent, importpath, id)
+        # For just import paths,
+        # use the import path as-is.
+        return importpath unless id
+
+        if id.split(".").count > 1
+          # If the target is a method or a struct,
+          # use $parent.$target.
+          text = id
+        else
+          # Otherwise use $pkg.$target.
+          pkg = pkgmap(parent.document.attributes)[importpath]
+          pkg ||= importpath.split("/")[-1]
+          text = "#{pkg}.#{id}"
+        end
+
+        node = create_inline parent, :quoted, text, { type: :monospaced }
+        node.convert
+      end
+
+      def process(parent, target, attrs)
+        importpath, id = target.split("#", 2)
+
+        text = attrs["text"] || generate_text(parent, importpath, id)
+        target = %(https://pkg.go.dev/#{importpath})
+        target << "##{id}" if id
+
+        parent.document.register :links, target
+        (create_anchor parent, text, type: :link, target: target).convert.to_s
+      end
+    end
+  end
+end

data/lib/asciidoctor/godoc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Godoc
+    VERSION = "0.1.0"
+  end
+end

data/lib/asciidoctor/godoc.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "asciidoctor/extensions"
+require_relative "godoc/inline_macro"
+require_relative "godoc/version"
+
+Asciidoctor::Extensions.register do
+  inline_macro Asciidoctor::Godoc::InlineMacro
+end

data/lib/asciidoctor-godoc.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "asciidoctor/godoc"

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-godoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Abhinav Gupta
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+description: An Asciidoctor extension that adds support for     a 'godoc' macro to
+  asciidoc documents.     This extension allows referencing Go entities in asciidoc
+  documents,     linking to their documentation on https://pkg.go.dev.
+email:
+- mail@abhinavg.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.adoc
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.adoc
+- Rakefile
+- lib/asciidoctor-godoc.rb
+- lib/asciidoctor/godoc.rb
+- lib/asciidoctor/godoc/inline_macro.rb
+- lib/asciidoctor/godoc/version.rb
+homepage: https://abhinav.github.io/asciidoctor-godoc/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://abhinav.github.io/asciidoctor-godoc/
+  source_code_uri: https://github.com/abhinav/asciidoctor-godoc
+  changelog_uri: https://github.com/abhinav/asciidoctor-godoc/blob/main/CHANGELOG.adoc
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: An Asciidoctor extension to add a 'godoc' macro.
+test_files: []