Creating codebase documentation on how to build the documentation

Review Request #7637 — Created Sept. 18, 2015 and submitted

Information

Review Board
master

Reviewers

Update: Wrapped to 80 chars

Opened generating-documentation.html after performing make html upon completion of creating the document.

Description From Last Updated

This file should be wrapped at 79 characters.

brenniebrennie

easy_install... I prefer pip, though.

brenniebrennie

This isn't particular to installing documentation. Also, apt-get will only work for users on Debian based systems.

brenniebrennie

"browse to..." We should put the path in double backquotes so it appears as monospaced text formated as code.

brenniebrennie

We don't need this split up into tiny sections. This can all go into one section (e.g., Building documentation).

brenniebrennie

Use double backquotes. I would also not use "get into" for changing directory. I would say something like The documentation …

brenniebrennie

Instead of "simply type the following" how about "install Sphinx via"

brenniebrennie

This can be replaced with something like "To generate the documentation, run the following:"

brenniebrennie

This doesn't really need to be here.

brenniebrennie

This should be double backticks, e.g. ``/reviewboard/docs/manual``

brenniebrennie

Likewise, this too.

brenniebrennie

Please wrap this to 80 characters.

daviddavid
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
  2. 
      
brennie
  1. <p>Please write a summary that describes the general issue and fill out the testing done. The bug number should also go in the bugs field.</p>
    <p>You don't need to include files that were added or modified in your change descriptions. You may want to read <a href="https://www.reviewboard.org/docs/codebase/dev/writing-good-descriptions/">Writing Good Descriptions</a>.</p>

  2. This file should be wrapped at 79 characters.

  3. easy_install...

    I prefer pip, though.

  4. docs/codebase/generating-documentation.rst (Diff revision 1)
     
     
     
     
     
     
     
     
     
     
     
     
     
     

    This isn't particular to installing documentation. Also, apt-get will only work for users on Debian based systems.

  5. "browse to..."

    We should put the path in double backquotes so it appears as monospaced text formated as code.

  6. 
      
chipx86
  1. Some of the steps here (like the Sphinx installation) are no longer going to be necessary once https://reviews.reviewboard.org/r/7629/ lands. You'll want to update the steps to refer to the Getting Started guide for those parts.

  2. 
      
CH
reviewbot
  1. Tool: Pyflakes
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
    
    Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
  2. 
      
david
  1. The summary here "Easyfix: 3703" isn't particularly helpful. It forces someone reading the git log to go to the bug tracker to find out what happened. We also would like more detail in the description, and some details on how you tested this.

    Please see https://www.reviewboard.org/docs/codebase/dev/writing-good-descriptions/

  2. 
      
CH
brennie
  1. 
      
  2. docs/codebase/generating-documentation.rst (Diff revision 2)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     

    We don't need this split up into tiny sections. This can all go into one section (e.g., Building documentation).

  3. Use double backquotes.

    I would also not use "get into" for changing directory. I would say something like

    The documentation resides in the ``/reviewboard/docs/manual`` directory.
    
  4. Instead of "simply type the following" how about "install Sphinx via"

  5. This can be replaced with something like "To generate the documentation, run the following:"

  6. This doesn't really need to be here.

  7. 
      
CH
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
  2. 
      
CH
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
  2. 
      
CH
CH
brennie
  1. 
      
  2. This should be double backticks, e.g.

    ``/reviewboard/docs/manual``
    
  3. Likewise, this too.

  4. 
      
CH
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
  2. 
      
david
  1. 
      
  2. Please wrap this to 80 characters.

  3. 
      
CH
reviewbot
  1. Tool: PEP8 Style Checker
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
    
    Tool: Pyflakes
    Ignored Files:
        docs/codebase/generating-documentation.rst
        docs/codebase/index.rst
    
    
  2. 
      
david
  1. Ship It!
  2. 
      
CH
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to release-2.5.x (8aeaea7)
Loading...