Add a basic user manual for rb-gateway.

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

david
rb-gateway
master
d7aa4ef...
rb-gateway

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. Missing webhookStorePath.

  3. Misisng webhookStorePath

  4. 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. 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)
     
     
     
     

    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)
     
     

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

  4. Can you add a rbgateway-configuration anchor?

  5. 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)
     
     
     
     
     
     

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

  7. Do we have a default?

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

  9. This can, I think, be:

    .. code-block:: ini
    
       <code...>
    
  10. 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. Can you add an rbgateway-installation anchor here?

  12. 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. 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

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

chipx86
  1. Looking good.

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

  3. 
      
chipx86
  1. 
      
  2. 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

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

chipx86
  1. Ship It!
  2. 
      
david
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to master (7c56760)
Loading...