Add a basic user manual for rb-gateway.

Review Request #10049 — Created June 29, 2018 and submitted

Information

rb-gateway
master
d7aa4ef...

Reviewers

This change adds a user manual for rb-gateway. It includes (very very
simple) installation instructions, and documentation on how to configure
and run the service.

Built HTML and viewed results.

Description From Last Updated

E501 line too long (87 > 79 characters)

reviewbotreviewbot

E501 line too long (108 > 79 characters)

reviewbotreviewbot

E501 line too long (104 > 79 characters)

reviewbotreviewbot

E501 line too long (104 > 79 characters)

reviewbotreviewbot

E501 line too long (83 > 79 characters)

reviewbotreviewbot

E303 too many blank lines (4)

reviewbotreviewbot

Can you add an anchor to this? Maybe rbgateway-index? That'll help with linking from the Review Board manual.

chipx86chipx86

The "... which can require additional APIs" feels a little redundant. Maybe just get rid of that bit.

chipx86chipx86

Can you add a rbgateway-configuration anchor?

chipx86chipx86

Rather than ::, this would be better with: .. code-block:: javascript <code here> That'll ensure syntax highlighting is correct.

chipx86chipx86

Missing webhookStorePath.

brenniebrennie

Definitions should be indented 4 spaces (here and below).

chipx86chipx86

Do we have a default?

chipx86chipx86

Misisng webhookStorePath

brenniebrennie

Above, we don't use colons after the name/type, but we do here. We should be consistent.

chipx86chipx86

Might want to mention this is also included as /contrib/rb-gateway.service

brenniebrennie

This can, I think, be: .. code-block:: ini <code...>

chipx86chipx86

How about a simple /usr/local/bin/rb-gateway and /etc/rb-gateway/? I know some things like /opt/rb-gateway/, but I feel like that's less standard …

chipx86chipx86

Can you add: ExecReload=/bin/kill -HUP $MAINPID This allows users to do systemctl reload rb-gateway Also, do you mind adding this …

brenniebrennie

Can you add an rbgateway-installation anchor here?

chipx86chipx86

I feel like we should provide more guidance here, and we should link to the download page (it'll be https://www.reviewboard.org/downloads/rbgateway/). …

chipx86chipx86

It also will need write access to the token store path and the webhook store path

brenniebrennie

E501 line too long (87 > 79 characters)

reviewbotreviewbot

E501 line too long (94 > 79 characters)

reviewbotreviewbot

E501 line too long (90 > 79 characters)

reviewbotreviewbot

E501 line too long (90 > 79 characters)

reviewbotreviewbot

E501 line too long (83 > 79 characters)

reviewbotreviewbot

E303 too many blank lines (4)

reviewbotreviewbot

I'm guessing we'd want /etc/rb-gateway/rb-gateway.conf, since there's also a webhooks.conf, right?

chipx86chipx86

I realized the flaw with my idea here is that we have a version per platform. So maybe latest/linux_amd64/, which …

chipx86chipx86

E501 line too long (87 > 79 characters)

reviewbotreviewbot

E501 line too long (94 > 79 characters)

reviewbotreviewbot

E501 line too long (90 > 79 characters)

reviewbotreviewbot

E501 line too long (90 > 79 characters)

reviewbotreviewbot

E501 line too long (83 > 79 characters)

reviewbotreviewbot

E303 too many blank lines (4)

reviewbotreviewbot
Checks run (1 failed, 1 succeeded)
flake8 failed.
JSHint passed.

flake8

brennie
  1. 
      
  2. Show all issues

    Missing webhookStorePath.

  3. Show all issues

    Misisng webhookStorePath

  4. Show all issues

    Might want to mention this is also included as /contrib/rb-gateway.service

    1. Seeing as that's part of the git repo and not distributed on the downloads page, I don't think that's a useful thing to mention.

  5. Show all issues

    It also will need write access to the token store path and the webhook store path

  6. 
      
chipx86
  1. 
      
  2. docs/rb-gateway/index.rst (Diff revision 1)
     
     
     
     
    Show all issues

    Can you add an anchor to this? Maybe rbgateway-index? That'll help with linking from the Review Board manual.

  3. docs/rb-gateway/index.rst (Diff revision 1)
     
     
    Show all issues

    The "... which can require additional APIs" feels a little redundant. Maybe just get rid of that bit.

  4. Show all issues

    Can you add a rbgateway-configuration anchor?

  5. Show all issues

    Rather than ::, this would be better with:

    .. code-block:: javascript
    
       <code here>
    

    That'll ensure syntax highlighting is correct.

  6. docs/rb-gateway/rb-gateway/configuration/index.rst (Diff revision 1)
     
     
     
     
     
     
    Show all issues

    Definitions should be indented 4 spaces (here and below).

  7. Show all issues

    Do we have a default?

  8. Show all issues

    Above, we don't use colons after the name/type, but we do here. We should be consistent.

  9. Show all issues

    This can, I think, be:

    .. code-block:: ini
    
       <code...>
    
  10. Show all issues

    How about a simple /usr/local/bin/rb-gateway and /etc/rb-gateway/? I know some things like /opt/rb-gateway/, but I feel like that's less standard and more prone to confusing people.

  11. Show all issues

    Can you add an rbgateway-installation anchor here?

  12. Show all issues

    I feel like we should provide more guidance here, and we should link to the download page (it'll be https://www.reviewboard.org/downloads/rbgateway/).

    I also think we can do something useful with providing a handy redirect on the site that points to the latest download (say, https://www.reviewboard.org/downloads/rbgateway/latest/), since the URL will be predictable and we know the version information on the server. With that, we can have something like:

    You can `download the latest version`_ of ``rb-gateway`` or view the
    `downloads page`_ for other options. Once downloaded, place the binary
    somewhere on your server (for example, on Linux,
    :file:`/usr/local/bin/rb-gateway`) and make it executable.
    
    You'll also need a place to store the configuration files (for example,
    :file:`/etc/rb-gateway/`).
    
    For example, to get started quickly on Linux:
    
        $ sudo curl https://www.reviewboard.org/downloads/rbgateway/latest/ \
               -O /usr/local/bin/rb-gateway
        $ sudo chmod +x /usr/local/bin/rb-gateway
        $ sudo mkdir /etc/rbgateway
    

    Once installed, follow the :ref:`configuration instructions <rbgateway-configuration>`
    to finish setting up your server.
    
    1. Technically it should go into /opt since its third party.

    2. Eh, I don't know about that. That's not really done in reality, generally-speaking, and can lead to more confusion than anything. /opt is more often used if you're dealing with a more self-contained installation environment (think a Bitnami install) rather than user-downloadable software.

  13. 
      
brennie
  1. 
      
  2. Show all issues

    Can you add:

    ExecReload=/bin/kill -HUP $MAINPID
    

    This allows users to do systemctl reload rb-gateway

    Also, do you mind adding this to the unit file as well?

  3. 
      
david
Review request changed
Commit:
6f3e85f8e45dcaee49993d0341a3149325d0411f
81d596861655731da229a5fe4b297ce33d6674a5

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

chipx86
  1. Looking good.

  2. Show all issues

    I'm guessing we'd want /etc/rb-gateway/rb-gateway.conf, since there's also a webhooks.conf, right?

  3. 
      
chipx86
  1. 
      
  2. Show all issues

    I realized the flaw with my idea here is that we have a version per platform. So maybe latest/linux_amd64/, which would map to the rbgateway-1.0-linux-amd64 (or, say, rbgateway-1.0-windows-amd64.exe).

  3. 
      
david
Review request changed
Commit:
81d596861655731da229a5fe4b297ce33d6674a5
d7aa4ef639399a694902af6a7d9aa1f10643f935

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

chipx86
  1. Ship It!
  2. 
      
david
Review request changed
Status:
Completed
Change Summary:
Pushed to master (7c56760)