|
| 1 | +# Documentation |
| 2 | + |
| 3 | +Code needs explanation, and sometimes those who know the code well have trouble explaining it to someone just getting into it. We welcome documentation suggestions and patches from everyone, especially from those new to RubyGems or Bundler. |
| 4 | + |
| 5 | +This repository contains documentation for both RubyGems and Bundler. We have multiple documentation sources depending on what you're documenting: |
| 6 | + |
| 7 | +## RubyGems Documentation |
| 8 | + |
| 9 | +**RubyGems guides**: https://guides.rubygems.org/ |
| 10 | + |
| 11 | +For RubyGems documentation contributions: |
| 12 | +- Submit issues or pull requests to the [RubyGems Guides repository](https://github.com/rubygems/guides) |
| 13 | +- This covers topics like gem creation, publishing, versioning, and best practices |
| 14 | + |
| 15 | +## Bundler Documentation |
| 16 | + |
| 17 | +**Bundler help & man pages**: Built into the `bundler/` directory |
| 18 | + |
| 19 | +**Bundler documentation site**: https://bundler.io |
| 20 | + |
| 21 | +For Bundler documentation contributions: |
| 22 | +- **Command documentation** (ex: `bundle clean`): Contribute to man pages in this repository (`bundler/lib/bundler/man/`) |
| 23 | +- **Guides and tutorials** (ex: "Using Bundler with Rails"): Open an issue or pull request in the [bundler-site](https://github.com/rubygems/bundler-site) repository |
| 24 | +- **Using Bundler with gems**: Additional documentation on [RubyGems guides](https://guides.rubygems.org/) |
| 25 | + |
| 26 | +## Documentation Vision and Goals |
| 27 | + |
| 28 | +### RubyGems |
| 29 | + |
| 30 | +RubyGems documentation focuses on: |
| 31 | +- Gem creation, packaging, and publishing |
| 32 | +- Dependency management best practices |
| 33 | +- Version constraints and semantic versioning |
| 34 | +- Security and trust topics |
| 35 | + |
| 36 | +Goals are to provide guides and tutorials at https://guides.rubygems.org/ that help users understand and effectively use RubyGems. |
| 37 | + |
| 38 | +### Bundler |
| 39 | + |
| 40 | +Bundler documentation is split across multiple places: |
| 41 | + |
| 42 | +1. Built-in `help` (including usage information and man pages) |
| 43 | +2. [Bundler documentation site](https://bundler.io) |
| 44 | +3. [RubyGems guides](https://guides.rubygems.org/) (for gem publishing topics) |
| 45 | + |
| 46 | +Bundler documentation should provide users with assistance: |
| 47 | + |
| 48 | +1. Installing Bundler |
| 49 | +2. Using Bundler to manage an application's dependencies |
| 50 | +3. Using Bundler to create, package, and publish gems |
| 51 | + |
| 52 | +Our goal is to provide three types of documentation: |
| 53 | + |
| 54 | +* High-level overviews that provide topical guidance |
| 55 | +* Step-by-step tutorials |
| 56 | +* Command-specific reference material for the CLI |
| 57 | + |
| 58 | +Additionally, this documentation should be readily available in a logical place and easy to follow. |
| 59 | + |
| 60 | +Someday, we'd like to create deep-dive reference material about the inner workings of Bundler. However, while this is part of our overall vision, it is not the focus of our current work. |
| 61 | + |
| 62 | +## Writing RubyGems Documentation |
| 63 | + |
| 64 | +### Contributing to RubyGems guides |
| 65 | + |
| 66 | +To contribute to RubyGems documentation: |
| 67 | + |
| 68 | +1. Fork and clone the [rubygems/guides](https://github.com/rubygems/guides) repository |
| 69 | +2. Add or edit Markdown files in the `_pages/` directory |
| 70 | +3. Follow the existing format and style guidelines |
| 71 | +4. Submit a pull request with your changes |
| 72 | + |
| 73 | +See the [RubyGems Guides repository](https://github.com/rubygems/guides) for detailed contribution instructions. |
| 74 | + |
| 75 | +## Writing Bundler Documentation |
| 76 | + |
| 77 | +### Writing docs for man pages |
| 78 | + |
| 79 | +*Any commands or file paths in this document assume that you are inside [the bundler/ directory of the ruby/rubygems repository](https://github.com/ruby/rubygems/tree/master/bundler).* |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | +_Note: `bundler` and `bundle` may be used interchangeably in the CLI. This guide uses `bundle` because it's cuter._ |
| 84 | + |
| 85 | +### What goes in man pages? |
| 86 | + |
| 87 | +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`). |
| 88 | + |
| 89 | +To see a list of commands available in the Bundler CLI, type: |
| 90 | + |
| 91 | + $ bundle help |
| 92 | + |
| 93 | +Our goal is to have a man page for every command. |
| 94 | + |
| 95 | +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. |
| 96 | + |
| 97 | +### Creating a new man page |
| 98 | + |
| 99 | +To create a new man page, simply create a new `.ronn` file in the `lib/bundler/man/` directory. |
| 100 | + |
| 101 | +For example: to create a man page for the command `bundle cookies` (not a real command, sadly), I would create a file `lib/bundler/man/bundle-cookies.1.ronn` and add my documentation there. |
| 102 | + |
| 103 | +### Formatting |
| 104 | + |
| 105 | +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. |
| 106 | + |
| 107 | +[The ronn guide formatting guide](https://rtomayko.github.io/ronn/ronn.7.html) provides a good overview of the common types of formatting. |
| 108 | + |
| 109 | +In general, make your page look like the other pages: utilize sections like `##OPTIONS` and formatting like code blocks and definition lists where appropriate. |
| 110 | + |
| 111 | +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. |
| 112 | + |
| 113 | +### Previewing |
| 114 | + |
| 115 | +To preview your changes as they will print out for Bundler users, you'll need to run a series of commands: |
| 116 | + |
| 117 | +``` |
| 118 | +$ bin/rake dev:deps |
| 119 | +$ bin/rake man:build |
| 120 | +$ man ./lib/bundler/man/bundle-cookies.1 |
| 121 | +``` |
| 122 | + |
| 123 | +If you make more changes to `bundle-cookies.1.ronn`, you'll need to run the `bin/rake man:build` again before previewing. |
| 124 | + |
| 125 | +### Testing |
| 126 | + |
| 127 | +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. |
| 128 | + |
| 129 | +``` |
| 130 | +$ bin/rspec ./spec/commands/help_spec.rb |
| 131 | +$ bin/rspec ./spec/quality_spec.rb |
| 132 | +``` |
| 133 | + |
| 134 | +## Writing docs for [the Bundler documentation site](https://bundler.io) |
| 135 | + |
| 136 | +### Primary commands and utilities |
| 137 | + |
| 138 | +If you'd like to submit a pull request for any of the primary commands or utilities on [the Bundler documentation site](https://bundler.io), please follow the instructions above for writing documentation for man pages from the `ruby/rubygems` repository. They are the same in each case. |
| 139 | + |
| 140 | +**Note**: Editing `.ronn` files from the `ruby/rubygems` repository for the primary commands and utilities documentation is all you need 🎉. There is no need to manually change anything in the `rubygems/bundler-site` repository, because the man pages and the docs for primary commands and utilities on [the Bundler documentation site](https://bundler.io) are one in the same. They are generated automatically from the `ruby/rubygems` repository's `.ronn` files when you run `bin/rake man:build`. |
| 141 | + |
| 142 | +### Guides and tutorials |
| 143 | + |
| 144 | +To add a guide or tutorial to the [Bundler documentation site](https://bundler.io): |
| 145 | + |
| 146 | +1. Go to the [bundler-site](https://github.com/rubygems/bundler-site) repository |
| 147 | +2. Navigate to `/bundler-site/source/current_version_of_bundler/guides` |
| 148 | +3. Add a new [Markdown file](https://guides.github.com/features/mastering-markdown/) (ending in `.md`) |
| 149 | +4. Format the title correctly: |
| 150 | + ``` |
| 151 | + --- |
| 152 | + title: Your Guide Title Here |
| 153 | + --- |
| 154 | + ``` |
| 155 | +5. Submit a pull request with your changes |
0 commit comments