mwoehlke-kitware
commented
3 years ago Comparing before and after is a good example of the changes visible in the generated documentation. Note how "before" switches between bold and not-bold in the plugin path. Also note the 'ā' vs. '->' in the immediately following paragraph.
On a high DPI screen, there's a noticeable difference in the clarity of the large logo on the front page, also š.
Start cleaning up the RTD documentation. In addition to a major change to how the source is written (which does not affect output; see below for details), the following changes are made:
conf.py, where it belongs. A KWIVER version is added to the same location. This gives us a single place, at least within the RTD contents, where version numbers and copyright year need to be kept up to date.|space|is removed; it isn't needed, especially with use of the built-in|version|.->withā) are also made. (Eventually I would like to systematize formatting of menu and keyboard-shortcut references, but that is low priority.)Last, this starts to aggressively reformat the reST source to improve ongoing maintenance. Since line breaks in the source do not affect the output, we should, just like we would do with C++ source code, use line breaks in a way that is beneficial to maintenance of the source. This means keeping lines to a reasonable length, and also inserting breaks in a way that will minimize "churn" from editing. (Specifically, not keeping text as tightly wrapped as possible such that changes are likely to reflow entire paragraphs. This is in contrast to text expected to be read primarily "in the raw", such as plain text documents or source code comments.) To that end, breaks should always be added at the end of sentences, and also at "logical" places within sentences which would otherwise be longer than the desired line length.
On a similar note, use of smart quotes is strongly discouraged in the source. These are a pain to type, and Sphinx will generate these automatically in the final documentation. Also, in some instances (e.g. text meant to be entered at a command prompt) they are outright wrong. These will be replaced with ASCII quotes as the above changes are rolled out.
The plan is to apply such reformatting to all documentation source files eventually, but for now only those files affected by the other changes have been (in some cases, partly) modified.
The effect of these changes should be visible in the RTD job.