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:

Status badges

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 jhpalmieri

  • Branch set to u/jhpalmieri/look-at-the-docs

comment:2 Changed 3 years ago by jhpalmieri

  • Commit set to 405df4c754f931fc566719a9bf7750127815e2d7
  • Status changed from new to needs_review

New commits:

405df4ctrac 26926: encourage ticket reviewers to look at the built documentation.

comment:3 Changed 3 years ago by jdemeyer

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 jhpalmieri

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 git

  • Commit changed from 405df4c754f931fc566719a9bf7750127815e2d7 to 9a356ed6923cca5b7d0da396db86a5b27d73fdaa

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

6b51521trac 26926: encourage ticket reviewers to look at the built documentation.
9a356edtrac 26926: add comment about hyperlinks

comment:6 Changed 3 years ago by jdemeyer

  • 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 embray

  • 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 vbraun

  • Branch changed from u/jhpalmieri/look-at-the-docs to 9a356ed6923cca5b7d0da396db86a5b27d73fdaa
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.