Creating codebase documentation on how to build the documentation
Review Request #7637 — Created Sept. 18, 2015 and submitted
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. |
brennie | |
easy_install... I prefer pip, though. |
brennie | |
This isn't particular to installing documentation. Also, apt-get will only work for users on Debian based systems. |
brennie | |
"browse to..." We should put the path in double backquotes so it appears as monospaced text formated as code. |
brennie | |
We don't need this split up into tiny sections. This can all go into one section (e.g., Building documentation). |
brennie | |
Use double backquotes. I would also not use "get into" for changing directory. I would say something like The documentation … |
brennie | |
Instead of "simply type the following" how about "install Sphinx via" |
brennie | |
This can be replaced with something like "To generate the documentation, run the following:" |
brennie | |
This doesn't really need to be here. |
brennie | |
This should be double backticks, e.g. ``/reviewboard/docs/manual`` |
brennie | |
Likewise, this too. |
brennie | |
Please wrap this to 80 characters. |
david |
-
<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> -
docs/codebase/generating-documentation.rst (Diff revision 1) This file should be wrapped at 79 characters.
-
-
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. -
docs/codebase/generating-documentation.rst (Diff revision 1) "browse to..."
We should put the path in double backquotes so it appears as monospaced text formated as code.
-
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.
-
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
-
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/
Change Summary:
Enhanced the summary, description, testing done, and bug number.
Summary: |
|
||||
---|---|---|---|---|---|
Testing Done: |
|
||||
Bugs: |
|
-
-
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).
-
docs/codebase/generating-documentation.rst (Diff revision 2) 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.
-
docs/codebase/generating-documentation.rst (Diff revision 2) Instead of "simply type the following" how about "install Sphinx via"
-
docs/codebase/generating-documentation.rst (Diff revision 2) This can be replaced with something like "To generate the documentation, run the following:"
-
Change Summary:
Joined up all the tiny sections, modified the wording of the instructions, changed to double quotes for directories.
Diff: |
Revision 3 (+25 -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
-
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
-
-
docs/codebase/generating-documentation.rst (Diff revision 4) This should be double backticks, e.g.
``/reviewboard/docs/manual``
-
Change Summary:
Update: Replaced double quotes with double backticks.
Description: |
|
||||||
---|---|---|---|---|---|---|---|
Branch: |
|
||||||
Diff: |
Revision 5 (+22) |
-
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
Change Summary:
Wrapped to 80 chars
Description: |
|
||||||
---|---|---|---|---|---|---|---|
Diff: |
Revision 6 (+24) |