diff options
| -rw-r--r-- | distro/common/man/man1/README.md | 39 |
1 files changed, 29 insertions, 10 deletions
diff --git a/distro/common/man/man1/README.md b/distro/common/man/man1/README.md index 8bb1614fdb..9a915fb4cc 100644 --- a/distro/common/man/man1/README.md +++ b/distro/common/man/man1/README.md @@ -1,34 +1,53 @@ # Man pages for Knife -The source of the Chef Documentation, located at http://docs.opscode.com/. +The source of the Chef Documentation is located at +http://docs.opscode.com/. -This README documents how the man pages for all of the Knife subcommands that are built into the chef-client are managed. +This README documents how the man pages for all of the Knife subcommands +that are built into the chef-client are managed. ## Source Files -The source files are located in the chef-docs repository: https://github.com/opscode/chef-docs +The source files are located in the chef-docs repository: +https://github.com/opscode/chef-docs -Each Knife subcommand has its own source folder. The folder naming pattern begins with man_. +Each Knife subcommand has its own source folder. The folder naming +pattern begins with man_. Each man page is a single file called index.html. In the conf.py file, the following settings are unique to each man page: -`today` setting is used to define the Chef version. This is because we don't want an arbitrary date populated in the file, yet we still need a version number. For example: `today = 'Chef 11.8`. +`today` setting is used to define the Chef version. This is because we +don't want an arbitrary date populated in the file, yet we still need a +version number. For example: `today = 'Chef 11.8`. -`project` setting is set to be the same as the name of the subcommand. For example: `project = u'knife-foo'`. +`project` setting is set to be the same as the name of the subcommand. +For example: `project = u'knife-foo'`. -`Options for man page output` settings are set to be similar across all man pages, but each one needs to be tailored specifically for the name of the man page. +`Options for man page output` settings are set to be similar across all +man pages, but each one needs to be tailored specifically for the name +of the man page. -All of the other settings in the General Configuration section should be left alone. These exist to ensure that all of the doc builds are sharing the right common elements and have the same overall presentation. +All of the other settings in the General Configuration section should be +left alone. These exist to ensure that all of the doc builds are sharing +the right common elements and have the same overall presentation. ## Building Docs -The docs are built using Sphinx and must be set to the `-b man` output. Currently, the man pages are built locally and then added to the Chef builds in chef-master. +The docs are built using Sphinx and must be set to the `-b man` output. +Currently, the man pages are built locally and then added to the Chef +builds in chef-master. ## Editing -These files should never be edited. All of the content is pulled in from elsewhere in the chef-docs repo at build time. If changes need to be made, those changes are done elsewhere and then the man pages must be rebuilt. This is to help ensure that all of the changes are made across all of the locations in which these documents need to live. For example, by design, every Knife subcommand with a man page also has an HTML doc at docs.opscode.com/knife_foo.html. +These files should never be edited. All of the content is pulled in from +elsewhere in the chef-docs repo at build time. If changes need to be +made, those changes are done elsewhere and then the man pages must be +rebuilt. This is to help ensure that all of the changes are made across +all of the locations in which these documents need to live. For example, +by design, every Knife subcommand with a man page also has an HTML doc +at docs.opscode.com/knife_foo.html. ## License |