Fix documentation glitches (AcademySoftwareFoundation#1337)

* Fix sphinx extensions in conf.py and requirements.txt Signed-off-by: Cary Phillips <[email protected]> * Fix documentation glitches * Rename Overview to OpenEXR, so the homepage browser tab says OpenEXR * Move Porting Guide and Symbol Visibility under Concepts Signed-off-by: Cary Phillips <[email protected]> --------- Signed-off-by: Cary Phillips <[email protected]>
cary-ilm · Mar 3, 2023 · c1dd267 · c1dd267
1 parent 8f1469f
commit c1dd267
Show file tree

Hide file tree

Showing 4 changed files with 91 additions and 57 deletions.
diff --git a/docs/API.rst b/docs/API.rst
@@ -14,8 +14,6 @@ The OpenEXR API
    HelloWorld
    ReadingAndWritingImageFiles
    OpenEXRCoreAPI
-   PortingGuide
-   SymbolVisibility
 
 * :ref:`genindex`
 
diff --git a/docs/SymbolVisibility.rst b/docs/SymbolVisibility.rst
@@ -24,14 +24,14 @@ mechanics, follow the same rules between gcc, clang, and
 msvc. However, types have richer information than they do in C. So,
 unless extra work is done, concepts for RTTI like the typeinfo and the
 vtable for virtual classes will be hidden, and not visible. These are
-referred to as "vague" linkage objects in some discussions. 
+referred to as "vague" linkage objects in some discussions.
 
 It is with the "vague" linkage objects where different properties
 arise. For example, if you have a template, it is happily instantiated
 in multiple compile units. If the typeinfo is hidden for one library,
 then this may cause things like dynamic_cast to fail because then the
 same typeinfo is not used, and even though one might think that
-ImfAttribute<Imath::Box2i> are the same in two places, because they
+``ImfAttribute<Imath::Box2i>`` are the same in two places, because they
 are instantiated in separate places, they may be considered different
 types. To compound the issue, there are different rules for this in
 different implementations. For example, a default gcc under linux
@@ -63,61 +63,92 @@ it also exports the types for the member types as well, which is not
 desired, so these are marked as N/A even though the compiler does
 allow that to happen.
 
-
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| C++ vs Compiler                  | MSVC                    | mingw                   | gcc                       | clang                          |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| function                         | ``dllexport/dllimport`` | ``dllexport/dllimport`` | ``visibility("default")`` | ``visibility("default")``      |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| hide a function                  | N/A                     | N/A                     | ``visibility("hidden")``  | ``visibility("hidden")``       |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| ``class(typeinfo)``              | N/A                     | N/A                     | ``visibility("default")`` | ``visibility("default")``      |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| template class                   | N/A                     | N/A                     | ``visibility("default")`` | ``type_visibility("default")`` |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| template data                    | N/A                     | N/A                     | ``visibility("default")`` | ``visibility("default")``      |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| class template<br> instantiation | ``dllexport/dllimport`` | N/A                     | N/A                       | ``visibility("default")``      |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| enum                             | N/A                     | N/A                     | auto unhides (N/A)        | ``type_visibility("default")`` |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
-| extern template                  | N/A                     | ``dllexport/dllimport`` | ``visibility("default")`` | ``visibility("default")``      |
-+----------------------------------+-------------------------+-------------------------+---------------------------+--------------------------------+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - C++ vs Compiler
+     - MSVC
+     - mingw
+     - gcc
+     - clang
+   * - function
+     - ``dllexport/dllimport``
+     - ``dllexport/dllimport``
+     - ``visibility("default")``
+     - ``visibility("default")``
+   * - hide a function
+     - N/A
+     - N/A
+     - ``visibility("hidden")``
+     - ``visibility("hidden")``
+   * - ``class(typeinfo)``
+     - N/A
+     - N/A
+     - ``visibility("default")``
+     - ``visibility("default")``
+   * - template class
+     - N/A
+     - N/A
+     - ``visibility("default")``
+     - ``type_visibility("default")``
+   * - template data
+     - N/A
+     - N/A
+     - ``visibility("default")``
+     - ``visibility("default")``
+   * - class template instantiation
+     - ``dllexport/dllimport``
+     - N/A
+     - N/A
+     - ``visibility("default")``
+   * - enum
+     - N/A
+     - N/A
+     - auto unhides (N/A)
+     - ``type_visibility("default")``
+   * - extern template
+     - N/A
+     - ``dllexport/dllimport``
+     - ``visibility("default")``
+     - ``visibility("default")``
 
 With this matrix in mind, we can see the maximal set of macros we need to
 provide throughout the code. *NB*: This does not mean that we need to
-declare all of these, just that they might be needed. `XXX` should be
-substituted for the particular library name being compiled.
-
-+----------------------------------+------------------------------------------------------------------+
-| macro name                       | purpose                                                          |
-+----------------------------------+------------------------------------------------------------------+
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT``                   | one of export or import for windows, visibility for others       |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT_TYPE``              | for declaring a class / struct as public (for typeinfo / vtable) |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_HIDDEN``                   | used to explicitly hide, especially members of types             |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT_TEMPLATE_TYPE``     | stating the template type should be visible                      |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT_EXTERN_TEMPLATE``   | exporting template types (i.e. extern side of extern template)   |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT_TEMPLATE_INSTANCE`` | exporting specific template instantiations (in cpp code)         |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT_TEMPLATE_DATA``     | exporting templated data blocks                                  |
-+----------------------------------+------------------------------------------------------------------+
-| ``XXX_EXPORT_ENUM``              | exporting enum types                                             |
-+----------------------------------+------------------------------------------------------------------+
+declare all of these, just that they might be needed. ``XXX`` should be
+substituted for the particular library name being compiled
+(``OPENEXR``, ``OPENEXRUTIL``, ``OPENEXRCORE``, ``IEX``,
+``ILMTHREAD``, ``IMATH``).
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - macro name
+     - purpose
+   * - ``XXX_EXPORT``
+     - one of export or import for windows, visibility for others
+   * - ``XXX_EXPORT_TYPE``
+     - for declaring a class / struct as public (for typeinfo / vtable)
+   * - ``XXX_HIDDEN``
+     - used to explicitly hide, especially members of types
+   * - ``XXX_EXPORT_TEMPLATE_TYPE``
+     - stating the template type should be visible
+   * - ``XXX_EXPORT_EXTERN_TEMPLATE``
+     - exporting template types (i.e. extern side of extern template)
+   * - ``XXX_EXPORT_TEMPLATE_INSTANCE``
+     - exporting specific template instantiations (in cpp code)
+   * - ``XXX_EXPORT_TEMPLATE_DATA``
+     - exporting templated data blocks
+   * - ``XXX_EXPORT_ENUM``
+     - exporting enum types
 
 For a new library, the preference might be to call ``XXX_EXPORT``
 something like ``XXX_FUNC``, and rename things such as ``XXX_EXPORT_TYPE``
 to ``XXX_TYPE`` for simplicity. However, historically, OpenEXR has used
 the ``_EXPORT`` tag, and so that is preserved for consistency.
 
-References
-==========
+---------
 
 * LLVM libc++ visibility macros: https://libcxx.llvm.org/docs/DesignDocs/VisibilityMacros.html
 

diff --git a/docs/concepts.rst b/docs/concepts.rst
@@ -17,3 +17,5 @@ OpenEXR Concepts
    InterpretingDeepPixels
    TheoryDeepPixels
    OpenEXRFileLayout
+   PortingGuide
+   SymbolVisibility
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,13 +2,13 @@
   SPDX-License-Identifier: BSD-3-Clause
   Copyright Contributors to the OpenEXR Project.
 
-.. _Overview:
+.. _OpenEXR:
 
-Overview
-########
+OpenEXR
+#######
 
 .. toctree::
-   :caption: Overview
+   :caption: OpenEXR
    :maxdepth: 1
 
 .. sidebar:: 
@@ -38,7 +38,9 @@ The OpenEXR project includes `Imath <https://imath.readthedocs.io>`_,
 a basic, light-weight, and efficient C++ representation of 2D and 3D
 vectors and matrices and other simple but useful mathematical objects,
 functions, and data types common in computer graphics applications,
-including the “half” 16-bit floating-point type.
+including the `half
+<https://imath.readthedocs.io/en/latest/classes/half.html>`_ 16-bit
+floating-point type.
 
 Imath also includes optional python bindings for all types and
 functions, including optimized implementations of vector and matrix
@@ -76,9 +78,10 @@ Community
 
 * **Contribute a Fix, Feature, or Improvement:**
 
-  - Read the `Contribution guidelines
+  - Read the `Contribution Guidelines
     <https://github.com/AcademySoftwareFoundation/openexr/blob/main/CONTRIBUTING.md>`_
-    and `Code of Conduct <https://github.com/AcademySoftwareFoundation/openexr/blob/main/CODE_OF_CONDUCT.md>`_
+    and `Code of Conduct
+    <https://github.com/AcademySoftwareFoundation/openexr/blob/main/CODE_OF_CONDUCT.md>`_
 
   - Sign the `Contributor License Agreement
     <https://contributor.easycla.lfx.linuxfoundation.org/#/cla/project/2e8710cb-e379-4116-a9ba-964f83618cc5/user/564e571e-12d7-4857-abd4-898939accdd7>`_