Opened 3 years ago
Closed 3 years ago
#26926 closed enhancement (fixed)
Add to the reviewer's checklist: look at the built documentation
Reported by: | jhpalmieri | Owned by: | |
---|---|---|---|
Priority: | minor | Milestone: | sage-8.7 |
Component: | documentation | Keywords: | |
Cc: | Merged in: | ||
Authors: | John Palmieri | Reviewers: | Jeroen Demeyer |
Report Upstream: | N/A | Work issues: | |
Branch: | 9a356ed (Commits, GitHub, GitLab) | Commit: | 9a356ed6923cca5b7d0da396db86a5b27d73fdaa |
Dependencies: | Stopgaps: |
Description
Reviewers should look at the built documentation to catch reST errors that don't stop the build but cause the docs to looks bad. One example: using `some_code`
for source code instead of ``some_code``
– single quotes cause the contents to be set in math mode, and then the underscore will cause a subscript, which is probably not what was intended.
Change History (8)
comment:1 Changed 3 years ago by
- Branch set to u/jhpalmieri/look-at-the-docs
comment:2 Changed 3 years ago by
- Commit set to 405df4c754f931fc566719a9bf7750127815e2d7
- Status changed from new to needs_review
comment:3 Changed 3 years ago by
This is good advice in theory, but I must admit that I don't do this myself. The main reason: I have better things to do with my time than wait for the docbuild to finish. And doing that on a remote machine (where I can easily build or test Sage) is inconvenient since I cannot easily look at the built documentation on a remote machine from my desktop machine. Sad but true...
Minor nitpick about this ticket: mention that hyperlinks should also be checked. Something like "...but that may cause badly formatted output or broken hyperlinks"
comment:4 Changed 3 years ago by
I think that many reviewers (and authors) don't do large chunks of what's already in the checklist (for example, run the tests). I think it's appropriate to request this so that it might be on someone's mind when they are reviewing a ticket. For me, if I'm running all of the tests, I just run make ptestlong
so the docs get built anyway. And as I'm sure you know, you can always do sage --docbuild reference/homology html
to just build that one part of the reference manual, and that doesn't take very long.
Good idea about hyperlinks.
comment:5 Changed 3 years ago by
- Commit changed from 405df4c754f931fc566719a9bf7750127815e2d7 to 9a356ed6923cca5b7d0da396db86a5b27d73fdaa
comment:6 Changed 3 years ago by
- Reviewers set to Jeroen Demeyer
- Status changed from needs_review to positive_review
Note that I didn't actually look at the documentation built by this ticket :-)
comment:7 Changed 3 years ago by
- Milestone changed from sage-8.6 to sage-8.7
Retarging tickets optimistically to the next milestone. If you are responsible for this ticket (either its reporter or owner) and don't believe you are likely to complete this ticket before the next release (8.7) please retarget this ticket's milestone to sage-pending or sage-wishlist.
comment:8 Changed 3 years ago by
- Branch changed from u/jhpalmieri/look-at-the-docs to 9a356ed6923cca5b7d0da396db86a5b27d73fdaa
- Resolution set to fixed
- Status changed from positive_review to closed
New commits:
trac 26926: encourage ticket reviewers to look at the built documentation.