Reorganize repo/readthedocs documentation (AcademySoftwareFoundation#…

…1332)

* Reorganize documentation, move content to readthedocs site

* Move content from README.md/repo-top-level to docs/readthedocs
* Move technical documentation/src/images to "technical" subdir
* CONTRIBUTING, GOVERNANCE, INSTALL, ASWF now on readthedocs

Signed-off-by: Cary Phillips <cary@ilm.com>

* Remove GOVERNANCE.md, CONTRIBUTING.md, INSTALL.md

Signed-off-by: Cary Phillips <cary@ilm.com>

* Typos in README.md

Signed-off-by: Cary Phillips <cary@ilm.com>

* Doc re-org, pass 2

Signed-off-by: Cary Phillips <cary@ilm.com>

* Use sphinx-press-theme, toc_redirect.rst

Signed-off-by: Cary Phillips <cary@ilm.com>

* windowExample1.small.png

Signed-off-by: Cary Phillips <cary@ilm.com>

* reader/writer

Signed-off-by: Cary Phillips <cary@ilm.com>

* copyright

Signed-off-by: Cary Phillips <cary@ilm.com>

* copyright, take 2

Signed-off-by: Cary Phillips <cary@ilm.com>

* Copyright notice in *.md

Signed-off-by: Cary Phillips <cary@ilm.com>

* fix links; use $ instead of %

Signed-off-by: Cary Phillips <cary@ilm.com>

---------

Signed-off-by: Cary Phillips <cary@ilm.com>

CHANGES.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 # OpenEXR Release Notes
 
 * [Version 3.1.5](#version-315-april-11-2022) April 11, 2022

CODE_OF_CONDUCT.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 # Code of Conduct
 
 The OpenEXR project abides by Linux Foundation's code of conduct,

CONTRIBUTING.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 # Contributing to OpenEXR
 
 Thank you for your interest in contributing to OpenEXR. This document
@@ -13,7 +16,7 @@ explains our contribution process and procedures:
 For a description of the roles and responsibilities of the various
 members of the OpenEXR community, see [GOVERNANCE](GOVERNANCE.md), and
 for further details, see the OpenEXR project's [Technical
-Charter](https://github.com/AcademySoftwareFoundation/openexr/blob/main/ASWF/charter/OpenEXR-Technical-Charter.md). Briefly,
+Charter](ASWF/charter/OpenEXR-Technical-Charter.md). Briefly,
 a "contributor" is anyone who submits content to the project, a
 "committer" reviews and approves such submissions, and the "Technical
 Steering Committee" provides general project oversight and governance.

CONTRIBUTORS.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 This is a list of contributors to the OpenEXR project, sorted
 alphabetically by first name.
 

GOVERNANCE.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 # OpenEXR Project Roles and Responsibilities
 
 OpenEXR is a project of the Academy Software Foundation and relies on

LICENSE.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 Copyright (c) Contributors to the OpenEXR Project. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

README.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 [![License](https://img.shields.io/github/license/AcademySoftwareFoundation/openexr)](LICENSE.md)
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2799/badge)](https://bestpractices.coreinfrastructure.org/projects/2799)
 [![Build Status](https://github.com/AcademySoftwareFoundation/openexr/workflows/CI/badge.svg)](https://github.com/AcademySoftwareFoundation/openexr/actions?query=workflow%3ACI)
@@ -6,7 +9,7 @@
 
 # OpenEXR
 
-<img align="right" src="docs/images/windowExample1.png">
+<img align="right" src="docs/technical/images/windowExample1.png">
 
 OpenEXR provides the specification and reference implementation of the
 EXR file format, the professional-grade image storage format of the
@@ -20,103 +23,7 @@ OpenEXR is widely used in host application software where accuracy is
 critical, such as photorealistic rendering, texture access, image
 compositing, deep compositing, and DI.
 
-### About OpenEXR
-
-OpenEXR is a project of the [Academy Software
-Foundation](https://www.aswf.io).  The format and library were
-originally developed by Industrial Light & Magic and first released
-in 2003.  Weta Digital, Walt Disney Animation Studios, Sony Pictures
-Imageworks, Pixar Animation Studios, DreamWorks, and other studios,
-companies, and individuals have made contributions to the code base.
-
-OpenEXR is included in the [VFX Reference
-Platform](https://vfxplatform.com).
-
-### OpenEXR Features
-
-* High dynamic range and color precision.
-* Support for 16-bit floating-point, 32-bit floating-point, and
-  32-bit integer pixels.
-* Multiple image compression algorithms, both lossless and lossy. Some of
-  the included codecs can achieve 2:1 lossless compression ratios on images
-  with film grain.  The lossy codecs have been tuned for visual quality and
-  decoding performance.
-* Extensibility. New compression codecs and image types can easily be added
-  by extending the C++ classes included in the OpenEXR software distribution.
-  New image attributes (strings, vectors, integers, etc.) can be added to
-  OpenEXR image headers without affecting backward compatibility with
-  existing OpenEXR applications. 
-* Support for stereoscopic image workflows and a generalization
-  to multi-views.
-* Flexible support for deep data: pixels can store a variable-length list
-  of samples and, thus, it is possible to store multiple values at different
-  depths for each pixel. Hard surfaces and volumetric data representations
-  are accommodated.
-* Multipart: ability to encode separate, but related, images in one file.
-  This allows for access to individual parts without the need to read other
-  parts in the file.
-* Versioning: OpenEXR source allows for user configurable C++
-  namespaces to provide protection when using multiple versions of the
-  library in the same process space.
-
-### OpenEXR and Imath Version 3
-
-With the release of OpenEXR 3, the Imath library formerly distributed
-via the IlmBase component of OpenEXR is now an independent library
-dependency, available for download from https://github.com/AcademySoftwareFoundation/Imath.
-You can choose to build OpenEXR against an external installation of
-Imath, or the default CMake configuration will download and build it
-automatically during the OpenEXR build process.  Note that the half
-16-bit floating point data type is included in Imath.
-
-See the [porting
-guide](https://github.com/AcademySoftwareFoundation/Imath/blob/master/docs/PortingGuide2-3.md)
-for details about differences from previous releases and how to
-address them. Also refer to the porting guide for details about
-changes to Imath.
-
-#### New Features in OpenEXR v3.1
-
-The 3.1 release of OpenEXR introduces a new library, OpenEXRCore,
-which is the result of a significant re-thinking of how OpenEXR
-manages file I/O and provides access to image data. It begins to
-address long-standing scalability issues with multithreaded image
-reading and writing.
-
-The OpenEXRCore library provides thread-safe, non-blocking access to
-files, which was not possible with the current API, where the
-framebuffer management is separate from read requests. It is written
-entirely in C and provides a new C-language API alongside the existing
-C++ API. This new low-level API allows applications to do custom
-unpacking of EXR data, such as on the GPU, while still benefiting from
-efficient I/O, file validation, and other semantics. It provides
-efficient direct access to EXR files in texturing applications. This C
-library also introduces an easier path to implementing OpenEXR
-bindings in other languages, such as Rust.
-
-The 3.1 release represents a technology preview for upcoming
-releases. The initial release is incremental; the existing API and
-underlying behavior has not changed. The new API is available now for
-performance validation testing, and then in future OpenEXR releases,
-the C++ API will migrate to use the new core in stages. It is not the
-intention to entirely deprecate the C++ API, nor must all applications
-re-implement EXR I/O in terms of the C library. The C API does not,
-and will not, provide the rich set of utility classes that exist in
-the C++ layer. The 3.1 release of the OpenEXRCore library simply
-offers new functionality for specialty applications seeking the
-highest possible performance. In the future, the ABI will evolve, but
-the API will remain consistent, or only have additions.
-
-See [Reading and Writing OpenEXR Image Files with the C-language
-API](https://openexr.readthedocs.io/en/latest/OpenEXRCoreAPI.html)
-for more information.
-
-### Supported Platforms
-
-OpenEXR builds on Linux, macOS, Microsoft Windows, and is
-cross-compilable on other systems.
-
-### OpenEXR Project Mission
+## OpenEXR Project Mission
 
 The goal of the OpenEXR project is to keep the EXR format reliable and
 modern and to maintain its place as the preferred image format for
@@ -141,72 +48,108 @@ correctness and verifiability, and breadth of adoption. Imath is not
 intended to be a comprehensive linear algebra or numerical analysis
 package.
 
-### OpenEXR Project Governance
+# Project Governance
 
-OpenEXR is hosted by the Academy Software Foundation. See
-[GOVERNANCE](GOVERNANCE.md) for more information about how the project
-operates.
+OpenEXR is a project of the [Academy Software
+Foundation](https://www.aswf.io). See the project's [governance
+policies](GOVERNANCE.md), [contribution guidelines](CONTRIBzuTING.md), and [code of conduct](CODE_OF_CONDUCT)
+for more information.
 
-The OpenEXR project is dedicated to promoting a harassment-free
-community. Read our [code of conduct](CODE_OF_CONDUCT.md).
+# Quick Start
 
-## Developer Quick Start
+See the [technical documentation](https://openexr.readthedocs.io) for
+complete details, but to get started, the "hello, world" `.exr` writer program is:
 
-See [INSTALL](INSTALL.md) for instructions on downloading and building OpenEXR
-from source.
+    #include <ImfRgbaFile.h>
+    #include <ImfArray.h>
+    #include <iostream>
+
+    int
+    main()
+    {
+        try {
+            int width =  10;
+            int height = 10;
+            
+            Imf::Array2D<Imf::Rgba> pixels(width, height);
+            for (int y=0; y<height; y++)
+                for (int x=0; x<width; x++)
+                    pixels[y][x] = Imf::Rgba(0, x / (width-1.0f), y / (height-1.0f));
+        
+            Imf::RgbaOutputFile file ("hello.exr", width, height, Imf::WRITE_RGBA);
+            file.setFrameBuffer (&pixels[0][0], 1, width);
+            file.writePixels (height);
+        } catch (const std::exception &e) {
+            std::cerr << "Unable to read image file hello.exr:" << e.what() << std::endl;
+            return 1;
+        }
+        return 0;
+    }
 
-## Resources
+The `CMakeLists.txt` to build:
 
-* Website: http://www.openexr.com
+    cmake_minimum_required(VERSION 3.10)
+    project(exrwriter)
+    find_package(OpenEXR REQUIRED)
+
+    add_executable(${PROJECT_NAME} writer.cpp)
+    target_link_libraries(${PROJECT_NAME} OpenEXR::OpenEXR)
 
-* GitHub repository: http://www.github.com/AcademySoftwareFoundation/openexr
+To build:
 
-* Technical Documentation: https://openexr.readthedocs.io
+    $ mkdir _build
+    $ cmake -S . -B _build
+    $ make --build _build
 
-* Reference images: https://github.com/AcademySoftwareFoundation/openexr-images.
+For more details, see [The OpenEXR
+API](https://openexr.readthedocs.io/en/latest/API.html#the-openexr-api).
 
-### Getting Help
+# Community
 
-There are several ways to connect with the OpenEXR project:
+* **Ask a question:**
 
-* The openexr-dev@lists.aswf.io mail list: This is a development
-  focused mail list with a deep history of technical conversations and
-  decisions that have shaped the project. Subscribe at
-  [openexr-dev@lists.aswf.io](https://lists.aswf.io/g/openexr-dev).
+  - Email: openexr-dev@lists.aswf.io
 
-* ASWF Slack channel: [#openexr](https://academysoftwarefdn.slack.com/archives/CMLRW4N73)
-
-* GitHub Issues: GitHub issues are used both to track bugs and to
-  discuss feature requests.
+  - Slack: [academysoftwarefdn#openexr](https://academysoftwarefdn.slack.com/archives/CMLRW4N73)
+
+* **Attend a meeting:**
+
+  - Technical Steering Committee meetings are open to the
+    public, fortnightly on Thursdays, 1:30pm Pacific Time.
+
+  - Calendar: https://lists.aswf.io/g/openexr-dev/calendar
 
-See [CONTRIBUTING](CONTRIBUTING.md) for more information.
+* **Report a bug:**
 
-### Getting Involved
+  - Submit an Issue: https://github.com/AcademySoftwareFoundation/openexr/issues
 
-OpenEXR welcomes contributions to the project. See
-[CONTRIBUTING](CONTRIBUTING.md) for more information about
-contributing to OpenEXR.
+* **Report a security vulnerability:**
 
-## License
+  - Email to security@openexr.com
+
+* **Make a contribution:**
+
+  - Read the [contribution guidelines](CONTRIBUTING.md) and [code of conduct](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)
+
+  - Submit a PR: https://github.com/AcademySoftwareFoundation/openexr/pulls
 
-OpenEXR is released under the [BSD-3-Clause](LICENSE) license. See
-[PATENTS](PATENTS) for license information about portions of
-OpenEXR that are provided under a different license.
+# Resources
 
-## Frequently Asked Questions
+- Website: http://www.openexr.com
+- Technical documentation: https://openexr.readthedocs.io
+- Porting help: [OpenEXR/Imath Version 2.x to 3.x Porting Guide](https://openexr.readthedocs.io/en/latest/PortingGuide.html)
+- Reference images: https://github.com/AcademySoftwareFoundation/openexr-images
+- Security policy: [SECURITY.md](SECURITY.md)
+- Release notes: [CHANGES.md](CHANGES.md)
+- Contributors: [CONTRIBUTORS.md](CONTRIBUTORS.md)  
 
-* "``pip install openexr`` doesn't work."
+# License
 
-  The OpenEXR project provides python bindings for the Imath
-  vector/matrix classes, but it does *not* provide python bindings for
-  reading, writing, or editing .exr files.  The
-  [openexrpython](https://github.com/jamesbowman/openexrpython) module
-  is not affiliated with the OpenEXR project or the ASWF. Please
-  direct questions there.
+OpenEXR is licensed under the [BSD-3-Clause license](LICENSE.md).
 
-  Alternatively,
-  [OpenImageIO](https://sites.google.com/site/openimageio/home) also
-  includes python bindings for OpenEXR.
 
 ---
 

SECURITY.md

@@ -1,3 +1,6 @@
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright (c) Contributors to the OpenEXR Project -->
+
 # Security Policy
 
 ## Reporting a Vulnerability