diff options
author | The Bundler Bot <bot@bundler.io> | 2017-01-24 13:37:44 +0000 |
---|---|---|
committer | The Bundler Bot <bot@bundler.io> | 2017-01-24 13:37:44 +0000 |
commit | 43d3609d0d800846e25422daccbaa636b73e31d9 (patch) | |
tree | 6771f88ab85cc3fc02a4fb033354b58f6856158f /doc/documentation/WRITING.md | |
parent | 5a8ad746f4e560e8d7d6eded47e83ff99ac656b6 (diff) | |
parent | 5aec4a55c259965feedecaefcd6ceeff19b7c9de (diff) | |
download | bundler-43d3609d0d800846e25422daccbaa636b73e31d9.tar.gz |
Auto merge of #5350 - feministy:docs-reorg, r=indirect
[docs] consolidate all docs into sub folder
👋 goodness, that was a lot of typing! this is the first step of many for #5026.
the only section that isn't complete with these changes is `RELEASING.md`, which is in progress in #5252 (those changes will be moved into the proper location if this PR goes in first).
i made a few minor tweaks to the project's README to support this organization. i also left the code of conduct in the root.
~~one thing i *am concerned about* is that our little "guidelines for contributing" warning message on PRs is going to disappear after this gets merged because `CONTRIBUTING.md` is no longer in the root~~
~~should i put a file in the root called `CONTRIBUTING.md` that links to the docs for contributing? 🤔 i'm not 100% sure on how the github integration for that works so y'all let me know.~~
Diffstat (limited to 'doc/documentation/WRITING.md')
-rw-r--r-- | doc/documentation/WRITING.md | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/doc/documentation/WRITING.md b/doc/documentation/WRITING.md new file mode 100644 index 00000000..ce6dcce6 --- /dev/null +++ b/doc/documentation/WRITING.md @@ -0,0 +1,54 @@ +# Writing docs for man pages + +A primary source of help for Bundler users are the man pages: the output printed when you run `bundle help` (or `bundler help`). These pages can be a little tricky to format and preview, but are pretty straightforward once you get the hang of it. + +_Note: `bundler` and `bundle` may be used interchangeably in the CLI. This guide uses `bundle` because it's cuter._ + +## What goes in man pages? + +We use man pages for Bundler commands used in the CLI (command line interface). They can vary in length from large (see `bundle install`) to very short (see `bundle clean`). + +To see a list of commands available in the Bundler CLI, type: + + $ bundle help + +Our goal is to have a man page for every command. + +Don't see a man page for a command? Make a new page and send us a PR! We also welcome edits to existing pages. + +## Creating a new man page + +To create a new man page, simply create a new `.ronn` file in the `man/` directory. + +For example: to create a man page for the command `bundle cookies` (not a real command, sadly), I would create a file `man/bundle-cookies.ronn` and add my documentation there. + +## Formatting + +Our man pages use ronn formatting, a combination of Markdown and standard man page conventions. It can be a little weird getting used to it at first, especially if you've used Markdown a lot. + +[The ronn guide formatting guide](https://rtomayko.github.io/ronn/ronn.7.html) provides a good overview of the common types of formatting. + +In general, make your page look like the other pages: utilize sections like `##OPTIONS` and formatting like code blocks and definition lists where appropriate. + +If you're not sure if the formatting looks right, that's ok! Make a pull request with what you've got and we'll take a peek. + +## Previewing + +To preview your changes as they will print out for Bundler users, you'll need to run a series of commands: + +``` +$ rake spec:deps +$ rake man:build +$ man man/bundle-cookies.1 +``` + +If you make more changes to `bundle-cookies.ronn`, you'll need to run the `rake man:build` again before previewing. + +## Testing + +We have tests for our documentation! The most important test file to run before you make your pull request is the one for the `help` command and another for documentation quality. + +``` +$ rspec ./spec/commands/help_spec.rb +$ rspec ./spec/quality_spec.rb +``` |