docs: Fixes to formatting and sphinx warnings (#4301)

Also, tell doxygen to use multiple threads.

Signed-off-by: Larry Gritz <[email protected]>

src/doc/Doxyfile

@@ -440,6 +440,27 @@ TYPEDEF_HIDES_STRUCT   = NO
 
 LOOKUP_CACHE_SIZE      = 0
 
+# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use
+# during processing. When set to 0 doxygen will based this on the number of
+# cores available in the system. You can set it explicitly to a value larger
+# than 0 to get more control over the balance between CPU load and processing
+# speed. At this moment only the input processing can be done using multiple
+# threads. Since this is still an experimental feature the default is set to 1,
+# which effectively disables parallel processing. Please report any issues you
+# encounter. Generating dot graphs in parallel is controlled by the
+# DOT_NUM_THREADS setting.
+# Minimum value: 0, maximum value: 32, default value: 1.
+
+NUM_PROC_THREADS       = 0
+
+# If the TIMESTAMP tag is set different from NO then each generated page will
+# contain the date or date and time when the page was generated. Setting this to
+# NO can help when comparing the output of multiple runs.
+# Possible values are: YES, NO, DATETIME and DATE.
+# The default value is: NO.
+
+TIMESTAMP              = NO
+
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------

src/doc/builtinplugins.rst

@@ -1239,8 +1239,8 @@ control aspects of the writing itself:
    :header-rows: 1
 
    * - Output Configuration Attribute
-	 - Type
-	 - JPEG XL header data or explanation
+     - Type
+     - JPEG XL header data or explanation
    * - ``oiio:dither``
      - int
      - If nonzero and outputting UINT8 values in the file from a source of
@@ -1257,19 +1257,19 @@ control aspects of the writing itself:
        for output rather than being assumed to be associated and get automatic
        un-association to store in the file.
    * - ``compression``
-	 - string
-	 - If supplied, must be ``"jpegxl"``, but may optionally have a quality
-	   value appended, like ``"jpegxl:90"``. Quality can be 0-100, with 100
-	   meaning lossless.
+     - string
+     - If supplied, must be ``"jpegxl"``, but may optionally have a quality
+       value appended, like ``"jpegxl:90"``. Quality can be 0-100, with 100
+       meaning lossless.
    * - ``jpegxl:distance``
-	 - float
+     - float
      - Target visual distance in JND units, lower = higher quality.
        0.0 = mathematically lossless. 1.0 = visually lossless.
        Recommended range: 0.5 .. 3.0. Allowed range: 0.0 ... 25.0. 
        Mutually exclusive with ``*compression jpegxl:*```.
    * - ``jpegxl:effort``
      - int
-	 - Encoder effort setting. Range: 1 .. 10.
+     - Encoder effort setting. Range: 1 .. 10.
        Default: 7. Higher numbers allow more computation at the expense of time.
        For lossless, generally it will produce smaller files.
        For lossy, higher effort should more accurately reach the target quality.
@@ -1852,12 +1852,12 @@ attributes are supported:
      - int
      - If nonzero, the PNM file is big-endian (the default is little-endian).  
    * - ``pnm:pfmflip``
-      - int
-      - If this configuration hint is present and is zero, the automatic
-      vertical flipping of PFM image will be disabled (i.e., scanline 0 will
-      really be the first one stored in the file). If nonzero (the default),
-      float PFM files will store scanline 0 as the last scanline in the file
-      (i.e. the visual "top" of the image).
+     - int
+     - If this configuration hint is present and is zero, the automatic
+       vertical flipping of PFM image will be disabled (i.e., scanline 0 will
+       really be the first one stored in the file). If nonzero (the default),
+       float PFM files will store scanline 0 as the last scanline in the file
+       (i.e. the visual "top" of the image).
 
 **Configuration settings for PNM output**
 
@@ -1890,13 +1890,13 @@ control aspects of the writing itself:
        determine whether to write an ASCII or binary file.
        Float PFM files are always written in binary format.
    * - ``pnm:pfmflip``
-      - int
-      - If this configuration hint is present and is zero, for PFM files,
-      scanline 0 will really be stored first in the file, thus disabling the
-      usual automatically flipping that accounts for PFM files conventionally
-      being stored in bottom-to-top order. If nonzero (the default), float
-      PFM files will store scanline 0 as the last scanline in the file (i.e.
-      the visual "top" of the image).
+     - int
+     - If this configuration hint is present and is zero, for PFM files,
+       scanline 0 will really be stored first in the file, thus disabling the
+       usual automatically flipping that accounts for PFM files conventionally
+       being stored in bottom-to-top order. If nonzero (the default), float
+       PFM files will store scanline 0 as the last scanline in the file (i.e.
+       the visual "top" of the image).
 
 **Custom I/O Overrides**
 

src/doc/maketx.rst

@@ -12,7 +12,7 @@ Making Tiled MIP-Map Texture Files With `maketx` or `oiiotool`
 Overview
 ========
 
-The TextureSystem (Chapter :ref:`chap-texturesystem_`) will exhibit much
+The TextureSystem (Chapter :ref:`chap-texturesystem`) will exhibit much
 higher performance if the image files it uses as textures are tiled (versus
 scanline) orientation, have multiple subimages at different resolutions
 (MIP-mapped), and include a variety of header or metadata fields
@@ -56,7 +56,7 @@ Where *input* and *output* name the input image and desired output filename.
 The input files may be of any image format recognized by OpenImageIO (i.e.,
 for which ImageInput plugins are available).  The file format of the output
 image will be inferred from the file extension of the output filename (e.g.,
-:filename:`foo.tif` will write a TIFF file).
+`foo.tif` will write a TIFF file).
 
 Command-line arguments are:
 
@@ -511,7 +511,7 @@ Command-line arguments are:
 .. sec-oiiotooltex:
 
 `oiiotool`
-=========
+==========
 
 The :program:`oiiotool` utility (Chapter :ref:`chap-oiiotool`) is capable of
 writing textures using the `-otex` option, lat-long environment maps using the
@@ -630,9 +630,9 @@ detailed explanations of each, for the corresponding :program:`maketx`
 option):
 
 
-=======================     ============================================
+=========================   ============================================
 Appended Option             `maketx` equivalent
-=======================     ============================================
+=========================   ============================================
 `wrap=` *string*            `--wrap`
 `swrap=` *string*           `--swrap`
 `twrap=` *string*           `--twrap`
@@ -651,7 +651,7 @@ Appended Option             `maketx` equivalent
 `uvslopes_scale=` *float*   `--uvslopes-scale`
 `prman_metadata=1`          `--prman`
 `prman_options=1`           `--prman-metadata`
-=======================     ============================================
+=========================   ============================================
 
 
 Examples

src/doc/oiiointro.rst

@@ -230,7 +230,7 @@ OpenImageIO incorporates, distributes, or contains derived works of:
 
 * The SHA-1 implementation we use is public domain by Dominik Reichl  http://www.dominik-reichl.de/
 * PugiXML © 2006-2009 by Arseny Kapoulkine (based on work © 2003 Kristen Wegner), MIT license. http://pugixml.org/
-* DPX reader/writer © 2009 Patrick A. Palmer, BSD 3-clause license. https://github.com/patrickpalmer/dpx}
+* DPX reader/writer © 2009 Patrick A. Palmer, BSD 3-clause license. https://github.com/patrickpalmer/dpx
 * lookup3 code by Bob Jenkins, Public Domain. http://burtleburtle.net/bob/c/lookup3.c
 * xxhash © 2014 Yann Collet, BSD 2-clause license. https://github.com/Cyan4973/xxHash
 * farmhash © 2014 Google, Inc., MIT license. https://github.com/google/farmhash
@@ -244,8 +244,8 @@ OpenImageIO incorporates, distributes, or contains derived works of:
 * fmt library © Victor Zverovich. MIT license. https://github.com/fmtlib/fmt
 * UTF-8 decoder © 2008-2009 Bjoern Hoehrmann, MIT license. http://bjoern.hoehrmann.de/utf-8/decoder/dfa
 * Base-64 encoder © René Nyffenegger, Zlib license. http://www.adp-gmbh.ch/cpp/common/base64.html
-* stb_sprintf © 2017 Sean Barrett, public domain (or MIT license where that   may not apply). https://github.com/nothings/stb
-* bcdec.h bySergii "iOrange" Kudlai, MIT or Unlicense. https://github.com/iOrange/bcdec
+* stb_sprintf © 2017 Sean Barrett, public domain (or MIT license where that may not apply). https://github.com/nothings/stb
+* bcdec.h by Sergii "iOrange" Kudlai, MIT or Unlicense. https://github.com/iOrange/bcdec
 
 OpenImageIO Has the following build-time dependencies (using
 system installs, referencing as git submodules, or downloading as part of