Add documentation for integrations.

Review Request #9322 — Created Oct. 24, 2017 and submitted

Information

Review Board
release-3.0.x
9a21a09...

Reviewers

This change adds documentation for the top-level integrations UI, as
well as configuration docs for the three integrations shipped in
rb-integrations: CircleCI, Slack, and Travis CI.

  • Built HTML and checked the output.
  • Spell check.
Description From Last Updated

Looks good overall. Some small comments to reduce the density of some paragraphs (people tend to skim). Would you be …

chipx86chipx86

Maybe swap these? The order here will dictate navigation order in the sidebar (and maybe we'll want to rethink some …

chipx86chipx86

Maybe break "We recommend creating ..." into its own paragraph, since people tend to skim. Might be worth putting this …

chipx86chipx86

Can we reference the RBTools docs here?

chipx86chipx86

Can we also add a section showing an example configuration? I wouldn't know where to begin without seeing one.

chipx86chipx86

In another review I brought up adding a glossary.rst term for CI. Can we have that item cover both CI …

chipx86chipx86

The "should not include any secrets" bit is important enough to stand out as a .. warning::

chipx86chipx86
chipx86
  1. 
      
  2. Show all issues

    Looks good overall. Some small comments to reduce the density of some paragraphs (people tend to skim).

    Would you be up to adding screenshots showing the integrations page and some configuration for Travis/CI, so people can get a visual as they're setting things up?

    1. I've added a screenshot of the integration list and the conditions UI. Having a screenshot of the full config for each of the CI systems is probably a bit much since they're pretty big, but I think the conditions part one is the only one that's complex.

    2. Yeah that's fine. That's the best part to cover.

  3. docs/manual/admin/index.rst (Diff revision 1)
     
     
     
    Show all issues

    Maybe swap these? The order here will dictate navigation order in the sidebar (and maybe we'll want to rethink some of the existing order here...)

  4. docs/manual/admin/integrations/circle-ci.rst (Diff revision 1)
     
     
     
     
     
     
    Show all issues

    Maybe break "We recommend creating ..." into its own paragraph, since people tend to skim. Might be worth putting this into a .. note::.

  5. Show all issues

    Can we reference the RBTools docs here?

  6. docs/manual/admin/integrations/travis-ci.rst (Diff revision 1)
     
     
     
     
    Show all issues

    Can we also add a section showing an example configuration? I wouldn't know where to begin without seeing one.

  7. Show all issues

    In another review I brought up adding a glossary.rst term for CI. Can we have that item cover both CI and Continuous Integration, and use :term: here? Just for those who might be in here and don't understand what this is.

  8. docs/manual/admin/integrations/travis-ci.rst (Diff revision 1)
     
     
     
     
     
    Show all issues

    The "should not include any secrets" bit is important enough to stand out as a .. warning::

  9. 
      
david
chipx86
  1. Ship It!
  2. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to release-3.0.x (60ae0d5)