rneu31 / chef-web-docs

All The Documentation

chef-web-docs

This repo is the source of the Chef reference documentation located at https://docs.chef.io/

On October 23, 2016, it became easier to contribute to Chef reference documentation. For each topic, you now only have to make edits to a single file that looks a lot like the final HTML.

The fastest way to contribute

If you spot something in the docs that needs to be fixed, the fastest way to get the change in is to edit the file on the GitHub web site. To do this, click on the [edit on GitHub] link at the top of the page you want to edit. The link takes you to that topic's GitHub page. In GitHub, click on the pencil icon and make your changes. You can preview how they'll look right on the page ("Preview Changes" tab).

We no longer use "swaps" and include files, so you'll be able to see all of text in one place for each topic. If you need tips on the source language, check out these instructions.

When you're done editing, press the "Propose file change" button at the bottom of the page and confirm your pull request. The CI system will do some checks and add a comment to your PR with the results.

The Chef docs team can normally merge pull requests within a day or two. We'll fix build errors before we merge, so you don't have to worry about passing all of the CI checks, but it might add an extra few days. The important part is submitting your change.

The next fastest way

If your change involves edits to multiple topics, or if you contribute frequently, you'll want to fork this repo in GitHub, clone it on your workstation, and make pull requests from commits you push to your forked repo. After you fork chef/chef-web-docs using the GitHub web interface, clone the forked repo to your workstation, following these instructions.

After making your changes but before submitting a PR, run the shell command make master to check for errors and build a local version of the doc set in HTML for testing. Before running make master for the first time, you'll need to install Sphinx, the documentation generator, possibly using sudo:

  pip install sphinx==1.2.3

We currently require version 1.2.3 of Sphinx. You may also need to install Python, depending on your system.

The docs build in a minute or two. To view the local version you built, you have two options:

• Open the file build/<filename> in your browser
• Use a local web server like the http-server node module

Viewing your content using the http-server node module allows you to navigate through the documentation as if you were browsing it on https://docs.chef.io. To install and use the http-server module, do the following:

1. Install it through npm. Setting the -g flag allows you to use http-server from the command-line.

      npm install http-server -g

2. Navigate to the build directory.

3. Run http-server. After http-server starts up, connect to your docs through your loopback IP address (http://127.0.0.1:8080).

If you need tips on the source language for the docs, check out the instructions. We use a subset of restructuredText that's similar in scope to markdown.

Tagged regions

We studied how to make contributing to this doc set as easy as possible. We ended up choosing an approach that uses tagged regions delimited by .. tag and .. end_tag lines to denote shared blocks of text. The tagged regions act like include files, but they're visible inline and therefore easier to edit.

For more information about how tagged regions work and how our new dtags tool helps manage them, see the dtags README file and dtags help.

Sending feedback

We love getting feedback. You can use:

• Email --- Send an email to [e-mail] for documentation bugs, ideas, thoughts, and suggestions. This email address is not a support email address, however. If you need support, contact Chef support.
• Pull request --- Submit a PR to this repo using either of the two methods described above.
• GitHub issues --- Use the https://github.com/chef/chef/issues page for issues specific to Chef itself. This is a good place for "important" documentation bugs that may need visibility among a larger group, especially in situations where a doc bug may also surface a product bug. You can also use chef-web-docs issues, especially for docs feature requests and minor docs bugs.
• https://discourse.chef.io/ --- This is a great place to interact with Chef and others.

License

Creative Commons Attribution 3.0 Unported License

Archive of pre-2016 commit history

Commit history of this repo prior to February 12, 2016 has been archived to the chef/chef-web-docs-2016 repo to save space. No changes to the archive repo will be merged; it's just for historical purposes.

Questions?

Open an issue and ask. Or send email to [e-mail].