Documentation Changes #1815
Merged
Documentation Changes #1815
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Sure, thanks! |
|
I like the way this restructures the documentation and also provides a few good examples. Nice work :) I have some ideas for generating the "cli-reference" page automatically from the code, and I'll try to get to that soon. Thanks again for improving fpm for folks! |
I did it using VSCode's multiple cursors feature and some manual formatting; a programmatic solution would be great!
Thanks! |
|
using VSCode's multiple cursors feature
Clever!
I merged the automated cli docs stuff a few moments ago. I probably missed
a few formatting or other issues, though.
Would love your feedback if you can:
https://fpm.readthedocs.io/en/latest/cli-reference.html
…On Sun, Aug 15, 2021 at 11:20 PM Vedant K ***@***.***> wrote:
I have some ideas for generating the "cli-reference" page automatically
from the code, and I'll try to get to that soon.
I did it using VSCode's multiple cursors feature and some manual
formatting; a programmatic solution would be great!
I like the way this restructures the documentation and also provides a few
good examples. Nice work :)
Thanks!
—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
<#1815 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AABAF2W3RE6YO7VYDVPLRK3T5CUZXANCNFSM5BVNOWDQ>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email>
.
|
|
It looks great; one thing I noticed was some flag names were not properly formatted as code: Perhaps it is because of the trailing space after the options, maybe calling |
|
Here's a diff to fix that issue: diff --git a/docs/generate-cli-reference.rb b/docs/generate-cli-reference.rb
index 84f71c6..0ed8b54 100644
--- a/docs/generate-cli-reference.rb
+++ b/docs/generate-cli-reference.rb
@@ -18,13 +18,13 @@ FPM::Command.instance_variable_get(:@declared_options).each do |o
8000
ption|
if option.type == :flag
# it's a flag which means there are no parameters to the option
- puts "* ``#{option.switches.first}``"
+ puts "* ``#{option.switches.first.strip}``"
else
- puts "* ``#{option.switches.first} #{option.type}``"
+ puts "* ``#{option.switches.first} #{option.type.strip}``"
end
if option.switches.length > 1
- puts " - Alternate option spellings: ``#{option.switches[1..].join(", ")}``"
+ puts " - Alternate option spellings: ``#{option.switches[1..].join(", ").strip}``"
end
puts " - #{text}"
puts
@@ -42,9 +42,9 @@ FPM::Package.types.sort_by { |k,v| k }.each do |name, type|
options.sort_by { |flag, _| flag }.each do |flag, param, help, options, block|
if param == :flag
- puts "* ``#{flag.first}``"
+ puts "* ``#{flag.first.strip}``"
else
- puts "* ``#{flag.first} #{param}``"
+ puts "* ``#{flag.first} #{param.strip}``"
end
text = help.sub(/^\([^)]+\) /, "")I'd be happy to open a PR, if needed |
|
Also, the output-type-specific options have been nicely divided into their own sub-sections as well; but they still appear under General options. |
|
Diff for both the above fixes: diff --git a/docs/generate-cli-reference.rb b/docs/generate-cli-reference.rb
index 84f71c6..b2e9afb 100644
--- a/docs/generate-cli-reference.rb
+++ b/docs/generate-cli-reference.rb
@@ -12,22 +12,26 @@ puts
puts "General Options"
puts "---------------"
+puts
FPM::Command.instance_variable_get(:@declared_options).each do |option|
text = option.description.gsub("\n", " ")
- if option.type == :flag
- # it's a flag which means there are no parameters to the option
- puts "* ``#{option.switches.first}``"
- else
- puts "* ``#{option.switches.first} #{option.type}``"
- end
+ # Don't show output-format-specific options, they get their own section
// This method is a bit hacky, any better way to do it?
+ if !text.include? "only)"
+ if option.type == :flag
+ # it's a flag which means there are no parameters to the option
+ puts "* ``#{option.switches.first.strip}``"
+ else
+ puts "* ``#{option.switches.first} #{option.type.strip}``"
+ end
- if option.switches.length > 1
- puts " - Alternate option spellings: ``#{option.switches[1..].join(", ")}``"
+ if option.switches.length > 1
+ puts " - Alternate option spellings: ``#{option.switches[1..].join(", ").strip}``"
+ end
+ puts " - #{text}"
+ puts
end
- puts " - #{text}"
- puts
end
FPM::Package.types.sort_by { |k,v| k }.each do |name, type|
@@ -42,9 +46,9 @@ FPM::Package.types.sort_by { |k,v| k }.each do |name, type|
options.sort_by { |flag, _| flag }.each do |flag, param, help, options, block|
if param == :flag
- puts "* ``#{flag.first}``"
+ puts "* ``#{flag.first.strip}``"
else
- puts "* ``#{flag.first} #{param}``"
+ puts "* ``#{flag.first} #{param.strip}``"
end
text = help.sub(/^\([^)]+\) /, "")My fork has these changes, let me know if I should open a PR. Thanks! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Hi!
Hi there! First off, thanks to all the contributors for creating such a wonderful tool! I have used FPM for many of my projects, and I thought I might express my thanks by giving back to the community.
What this PR changes
I noticed that the docs were a bit incomplete - though installation instructions were pretty clear, there was no actual tutorial/getting started guide. This PR aims to add a bit of introductory material to the FPM docs.
Changes made:
.fpmconfiguration file.Related issues
#1744 #1718
Screenshots of the new documentation
Landing/Index page
Installation page
Getting started page
CLI reference page
Contributing page
Please do let me know if there can be any improvements to the changes made in this PR. Also let me know if some of these changes should be added to the Github Wiki for this project?
Thanks and regards!