Merge pull request #434 from DannyBen/add/mandoc-custom-see-also

DannyBen · web-flow · commit 66d798f76b42 · 2023-09-04T11:04:07.000+03:00
Add support for custom "See Also" in mandoc renderer (`x_mandoc_see_also`)
diff --git a/examples/render-mandoc/docs/download.1 b/examples/render-mandoc/docs/download.1
@@ -14,7 +14,7 @@
 . ftr VB CB
 . ftr VBI CBI
 .\}
-.TH "download" "1" "August 2023" "Version 0.1.0" "Sample application"
+.TH "download" "1" "September 2023" "Version 0.1.0" "Sample application"
 .hy
 .SH NAME
 .PP
@@ -50,6 +50,9 @@ Show debug information
 .SS aws-cli
 .PP
 Download from <https://aws.amazon.com/cli/>
+.SH SEE ALSO
+.PP
+\f[B]docker\f[R](1), \f[B]docker-compose.yml\f[R](5)
 .SH ISSUE TRACKER
 .PP
 Report issues at <https://github.com/lanalang/smallville>
diff --git a/examples/render-mandoc/docs/download.md b/examples/render-mandoc/docs/download.md
@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% August 2023
+% September 2023
 
 NAME
 ==================================================
@@ -60,5 +60,10 @@ aws-cli
 Download from \<https://aws.amazon.com/cli/\>
 
 
+SEE ALSO
+==================================================
+
+**docker**(1), **docker-compose.yml**(5)
+
 # ISSUE TRACKER
 Report issues at \<https://github.com/lanalang/smallville\>
diff --git a/examples/render-mandoc/src/bashly.yml b/examples/render-mandoc/src/bashly.yml
@@ -8,6 +8,9 @@ x_mandoc_authors: Lana Lang
 x_mandoc_footer: |-
   # ISSUE TRACKER
   Report issues at <https://github.com/lanalang/smallville>
+x_mandoc_see_also:
+  - docker
+  - docker-compose.yml(5)
 
 dependencies:
   aws-cli: Download from <https://aws.amazon.com/cli/>
diff --git a/lib/bashly/libraries/render/mandoc/README.md b/lib/bashly/libraries/render/mandoc/README.md
@@ -43,3 +43,21 @@ Add an authors string to your man pages.
 ```yaml
 x_mandoc_authors: Lana Lang
 ```
+
+### See Also: `x_mandoc_see_also`
+
+Adds additional pages to the `SEE ALSO` section, in addition to the
+pages that are added automatically (like the parent command, and
+sub commands).
+
+This property should be an array of strings. You can optionally add
+a section number in parentheses. If not provided, `(1)` will be used
+as default.
+
+#### Example
+
+```yaml
+x_mandoc_see_also:
+  - docker
+  - docker-compose.yml(5)
+```
diff --git a/lib/bashly/libraries/render/mandoc/mandoc.gtx b/lib/bashly/libraries/render/mandoc/mandoc.gtx
@@ -181,14 +181,19 @@ if examples
   >
 end
 
-if public_commands.any? || parents.any?
+see_also = []
+see_also << parents.first if parents.any?
+see_also += public_commands.map { |x| x.full_name.to_hyphen } if public_commands.any?
+see_also += x_mandoc_see_also if x_mandoc_see_also && x_mandoc_see_also.is_a?(Array)
+see_also.map! do |item|
+  item.match(/(.+)(\(\d\))/) ? "**#{$1}**#{$2}" : "**#{item}**(1)"
+end
+
+if see_also.any?
   > SEE ALSO
   > ==================================================
   >
-  if parents.any?
-    > **{{ parents.first }}**(1)
-  end
-  = public_commands.map { |x| "**#{x.full_name.to_hyphen}**(1)" }.join ', '
+  = see_also.join ', '
   >
 end
 
diff --git a/spec/approvals/examples/render-mandoc b/spec/approvals/examples/render-mandoc
@@ -35,10 +35,13 @@ DEPENDENCIES
    aws-cli
        Download from <https://aws.amazon.com/cli/>
 
+SEE ALSO
+       docker(1), docker-compose.yml(5)
+
 ISSUE TRACKER
        Report issues at <https://github.com/lanalang/smallville>
 
 AUTHORS
        Lana Lang.
 
-Version 0.1.0                     August 2023                      download(1)
+Version 0.1.0                   September 2023                     download(1)
diff --git a/spec/approvals/libraries/render/mandoc/render-1-download.1 b/spec/approvals/libraries/render/mandoc/render-1-download.1
@@ -29,4 +29,4 @@ EXAMPLES
               download example.com ./output -f
 
 
-Version 0.1.0                     August 2023                      download(1)
+Version 0.1.0                   MONTH YEAR                     download(1)
diff --git a/spec/approvals/libraries/render/mandoc/render-1-download.md b/spec/approvals/libraries/render/mandoc/render-1-download.md
@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample minimal application without commands
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
diff --git a/spec/approvals/libraries/render/mandoc/render-2-download.md b/spec/approvals/libraries/render/mandoc/render-2-download.md
@@ -1,6 +1,6 @@
 % cli-download(1) | Download a file
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -69,4 +69,3 @@ SEE ALSO
 **cli**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/catch-all-advanced/cli-download.md b/spec/approvals/rendering/mandoc/catch-all-advanced/cli-download.md
@@ -1,6 +1,6 @@
 % cli-download(1) | Download a file
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -66,4 +66,3 @@ SEE ALSO
 **cli**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/catch-all-advanced/cli-upload.md b/spec/approvals/rendering/mandoc/catch-all-advanced/cli-upload.md
@@ -1,6 +1,6 @@
 % cli-upload(1) | Upload a file
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -25,4 +25,3 @@ SEE ALSO
 **cli**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/catch-all-advanced/cli.md b/spec/approvals/rendering/mandoc/catch-all-advanced/cli.md
@@ -1,6 +1,6 @@
 % cli(1) Version 0.1.0 | Sample application
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
diff --git a/spec/approvals/rendering/mandoc/dependencies-alt/cli-download.md b/spec/approvals/rendering/mandoc/dependencies-alt/cli-download.md
@@ -1,6 +1,6 @@
 % cli-download(1) | Download something
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -43,4 +43,3 @@ SEE ALSO
 **cli**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/dependencies-alt/cli.md b/spec/approvals/rendering/mandoc/dependencies-alt/cli.md
@@ -1,6 +1,6 @@
 % cli(1) Version 0.1.0 | Sample application that requires alternate dependencies
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker-container-run.md b/spec/approvals/rendering/mandoc/docker-like/docker-container-run.md
@@ -1,6 +1,6 @@
 % docker-container-run(1) | Run a container
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -34,4 +34,3 @@ SEE ALSO
 **docker**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker-container-stop.md b/spec/approvals/rendering/mandoc/docker-like/docker-container-stop.md
@@ -1,6 +1,6 @@
 % docker-container-stop(1) | Stop a container
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -34,4 +34,3 @@ SEE ALSO
 **docker**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker-container.md b/spec/approvals/rendering/mandoc/docker-like/docker-container.md
@@ -1,6 +1,6 @@
 % docker-container(1) | Container commands
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -36,7 +36,6 @@ Stop a container
 SEE ALSO
 ==================================================
 
-**docker**(1)
-**docker-container-run**(1), **docker-container-stop**(1)
+**docker**(1), **docker-container-run**(1), **docker-container-stop**(1)
 
 
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker-image-ls.md b/spec/approvals/rendering/mandoc/docker-like/docker-image-ls.md
@@ -1,6 +1,6 @@
 % docker-image-ls(1) | Show all images
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -25,4 +25,3 @@ SEE ALSO
 **docker**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker-image.md b/spec/approvals/rendering/mandoc/docker-like/docker-image.md
@@ -1,6 +1,6 @@
 % docker-image(1) | Image commands
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -31,7 +31,6 @@ Show all images
 SEE ALSO
 ==================================================
 
-**docker**(1)
-**docker-image-ls**(1)
+**docker**(1), **docker-image-ls**(1)
 
 
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker-ps.md b/spec/approvals/rendering/mandoc/docker-like/docker-ps.md
@@ -1,6 +1,6 @@
 % docker-ps(1) | List containers
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -33,4 +33,3 @@ SEE ALSO
 **docker**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/docker-like/docker.md b/spec/approvals/rendering/mandoc/docker-like/docker.md
@@ -1,6 +1,6 @@
 % docker(1) Version 0.1.0 | Docker example
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
diff --git a/spec/approvals/rendering/mandoc/extensible-delegate/mygit-pull.md b/spec/approvals/rendering/mandoc/extensible-delegate/mygit-pull.md
@@ -1,6 +1,6 @@
 % mygit-pull(1) | Pull from my repository
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -25,4 +25,3 @@ SEE ALSO
 **mygit**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/extensible-delegate/mygit-push.md b/spec/approvals/rendering/mandoc/extensible-delegate/mygit-push.md
@@ -1,6 +1,6 @@
 % mygit-push(1) | Push to my repository
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -25,4 +25,3 @@ SEE ALSO
 **mygit**(1)
 
 
-
diff --git a/spec/approvals/rendering/mandoc/extensible-delegate/mygit.md b/spec/approvals/rendering/mandoc/extensible-delegate/mygit.md
@@ -1,6 +1,6 @@
 % mygit(1) Version 0.1.0 | Sample application that delegates unknown commands to a different executable
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
diff --git a/spec/approvals/rendering/mandoc/minimal/download.md b/spec/approvals/rendering/mandoc/minimal/download.md
@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample minimal application without commands
 % 
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
diff --git a/spec/approvals/rendering/mandoc/render-mandoc/download.md b/spec/approvals/rendering/mandoc/render-mandoc/download.md
@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% August 2023
+% MONTH YEAR
 
 NAME
 ==================================================
@@ -60,5 +60,10 @@ aws-cli
 Download from \<https://aws.amazon.com/cli/\>
 
 
+SEE ALSO
+==================================================
+
+**docker**(1), **docker-compose.yml**(5)
+
 # ISSUE TRACKER
 Report issues at \<https://github.com/lanalang/smallville\>
diff --git a/spec/bashly/integration/rendering_mandoc_spec.rb b/spec/bashly/integration/rendering_mandoc_spec.rb
@@ -34,6 +34,7 @@
           basename = File.basename file
           expect(File.read file).to match_approval("rendering/mandoc/#{example}/#{basename}")
             .diff(leeway)
+            .except(/\w{3,9} 202\d/, 'MONTH YEAR')
 
           expect(File).to exist("#{target}/#{File.basename(file, '.md')}.1")
         end
diff --git a/spec/bashly/libraries/render_mandoc_spec.rb b/spec/bashly/libraries/render_mandoc_spec.rb
@@ -26,10 +26,12 @@
 
         expect(File.read "#{target}/download.md")
           .to match_approval('libraries/render/mandoc/render-1-download.md')
+          .except(/\w{3,9} 202\d/, 'MONTH YEAR')
 
         expect(`man "#{target}/download.1" | col -bx`)
           .to match_approval('libraries/render/mandoc/render-1-download.1')
           .diff(leeway)
+          .except(/\w{3,9} 202\d/, 'MONTH YEAR')
       end
     end
 
@@ -39,9 +41,11 @@
       it 'saves a markdown and man files for each command' do
         expect { subject.instance_eval render_script }
           .to output_approval('libraries/render/mandoc/render-2')
+          .except(/\w{3,9} 202\d/, 'MONTH YEAR')
 
         expect(File.read "#{target}/cli-download.md")
           .to match_approval('libraries/render/mandoc/render-2-download.md')
+          .except(/\w{3,9} 202\d/, 'MONTH YEAR')
 
         expect(File).to exist("#{target}/cli.1")
         expect(File).to exist("#{target}/cli-upload.1")

Original file line number	Diff line number	Diff line change
`@@ -29,4 +29,4 @@ EXAMPLES`
`29`	`29`	`download example.com ./output -f`
`30`	`30`
`31`	`31`
`32`		`-Version 0.1.0 August 2023 download(1)`
	`32`	`+Version 0.1.0 MONTH YEAR download(1)`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`% download(1) Version 0.1.0 \| Sample minimal application without commands`
`2`	`2`	`%`
`3`		`-% August 2023`
	`3`	`+% MONTH YEAR`
`4`	`4`
`5`	`5`	`NAME`
`6`	`6`	`==================================================`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`% cli-download(1) \| Download a file`
`2`	`2`	`%`
`3`		`-% August 2023`
	`3`	`+% MONTH YEAR`
`4`	`4`
`5`	`5`	`NAME`
`6`	`6`	`==================================================`
`@@ -69,4 +69,3 @@ SEE ALSO`
`69`	`69`	`cli(1)`
`70`	`70`
`71`	`71`
`72`		`-`