Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename "docs" to "website" #1504

Merged
merged 5 commits into from
Aug 7, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 16 additions & 12 deletions .github/workflows/ci_workflow.yml
Original file line number Diff line number Diff line change
Expand Up @@ -221,6 +221,8 @@ jobs:
mkdir _install
mkdir _build
mkdir _examples
- name: Install help2man
run: yum install -y help2man
- name: Configure
run: |
cmake .. \
Expand All @@ -230,7 +232,8 @@ jobs:
-DCMAKE_CXX_FLAGS=${{ matrix.cxx-flags }} \
-DCMAKE_VERBOSE_MAKEFILE:BOOL='OFF' \
-DBUILD_SHARED_LIBS=${{ matrix.build-shared }} \
-DOPENEXR_BUILD_TOOLS='ON' \
-DOPENEXR_INSTALL_TOOLS='ON' \
-DOPENEXR_INSTALL_DOCS='ON' \
-DOPENEXR_RUN_FUZZ_TESTS='OFF' \
-DOPENEXR_ENABLE_THREADING=${{ matrix.threads-enabled }}
working-directory: _build
Expand Down Expand Up @@ -363,7 +366,8 @@ jobs:
-DCMAKE_CXX_FLAGS=${{ matrix.cxx-flags }} \
-DCMAKE_VERBOSE_MAKEFILE:BOOL='OFF' \
-DBUILD_SHARED_LIBS=${{ matrix.build-shared }} \
-DOPENEXR_BUILD_TOOLS='ON' \
-DOPENEXR_INSTALL_TOOLS='ON' \
-DOPENEXR_INSTALL_DOCS='OFF' \
-DOPENEXR_RUN_FUZZ_TESTS='OFF'
working-directory: _build
- name: Build
Expand Down Expand Up @@ -497,7 +501,8 @@ jobs:
-DCMAKE_CXX_FLAGS=${{ matrix.cxx-flags }} \
-DCMAKE_VERBOSE_MAKEFILE:BOOL='OFF' \
-DBUILD_SHARED_LIBS=${{ matrix.build-shared }} \
-DOPENEXR_BUILD_TOOLS='ON' \
-DOPENEXR_INSTALL_TOOLS='ON' \
-DOPENEXR_INSTALL_DOCS='OFF' \
-DOPENEXR_RUN_FUZZ_TESTS='OFF'
shell: bash
working-directory: _build
Expand Down Expand Up @@ -534,16 +539,16 @@ jobs:
shell: bash
working-directory: _build

Docs:
Website:

# Build the documentation, using a process that mimics the readthedoc build.
# Build the website, using a process that mimics the readthedoc build.
#
# Note that this job does not actually build OpenEXR libraries or
# programs, it just runs doxygen, sphinx, and the
# docs/script/test_images.py script to generate the "Test Images"
# website/script/test_images.py script to generate the "Test Images"
# page.

name: 'Docs'
name: 'Website'
runs-on: ubuntu-latest

steps:
Expand All @@ -554,17 +559,16 @@ jobs:
- name: Install doxygen & imagemagick
# Need imagemagick for convert, to convert "Test Image" exrs to jpgs
# Need openexr for exrheader
# Need help2man for tool manpages
run: sudo apt-get install -y doxygen imagemagick openexr help2man
run: sudo apt-get install -y doxygen imagemagick openexr
- name: Install sphinx requirements
run: pip3 install -r docs/requirements.txt
run: pip3 install -r website/requirements.txt
- name: Configure
run: cmake .. -DBUILD_DOCS='ON'
run: cmake .. -DBUILD_WEBSITE='ON'
working-directory: _build
- name: Build
run: |
cmake --build . \
--target docs \
--target website \
--config Release
working-directory: _build

6 changes: 3 additions & 3 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,11 @@ build:
- openexr # for exrheader, for test images
jobs:
pre_build:
- python docs/scripts/test_images.py
- python website/scripts/test_images.py

sphinx:
configuration: docs/conf.py
configuration: website/conf.py

python:
install:
- requirements: docs/requirements.txt
- requirements: website/requirements.txt
13 changes: 10 additions & 3 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -122,9 +122,16 @@ if(NOT OPENEXR_IS_SUBPROJECT)
include(cmake/clang-format.cmake)
endif()

option(BUILD_DOCS "Set ON to build html documentation")
if (BUILD_DOCS AND NOT OPENEXR_IS_SUBPROJECT)
option(INSTALL_DOCS "Set ON to install html documentation" ON)
option(OPENEXR_INSTALL_DOCS "Set ON to install tool manpages")
if (OPENEXR_INSTALL_DOCS AND NOT OPENEXR_IS_SUBPROJECT)
add_subdirectory(docs)
endif()

option(BUILD_WEBSITE "Set ON to build website source")
if (BUILD_WEBSITE AND NOT OPENEXR_IS_SUBPROJECT)
add_subdirectory(website)
else()
# Even if not building the website, still make sure the website example code compiles.
add_subdirectory(website/src)
endif()

2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ submitted, in order to solicit feedback, try to get as much consensus
as possible, and alert all the stakeholders to be on the lookout for
the eventual PR when it appears.

* Trivial changes that don't affect functionality (typos, docs, tests)
* Trivial changes that don't affect functionality (typos, tests, website)
can be approved by the committer without review, after waiting at
least 48 hours.

Expand Down
2 changes: 1 addition & 1 deletion cmake/OpenEXRConfig.h.in
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@

/// \defgroup ExportMacros Macros to manage symbol visibility
///
/// See docs/SymbolVisibility.md for more discussion about the
/// See website/SymbolVisibility.rst for more discussion about the
/// motivation for these macros
///
/// If we are compiling a DLL for Windows, there needs to be custom
Expand Down
73 changes: 5 additions & 68 deletions docs/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3,73 +3,16 @@

set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})

find_package(Doxygen REQUIRED)
find_package(Sphinx REQUIRED)

include(FindPythonPackage)
find_python_package(sphinx-press-theme REQUIRED)

set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src/lib/OpenEXRCore)
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)

set(SPHINX_OPTS "-W" CACHE STRING "Sphinx build options")

set(OPENEXR_TEST_IMAGE_REPO "https://raw.githubusercontent.com/AcademySoftwareFoundation/openexr-images"
CACHE STRING "Repo for test images")
set(OPENEXR_TEST_IMAGE_TAG "main"
CACHE STRING "Tag for test image repo")

set(TEST_IMAGE_INDEX_FILE ${PROJECT_SOURCE_DIR}/docs/_test_images/index.rst)
set(TEST_IMAGE_PY_FILE ${PROJECT_SOURCE_DIR}/docs/scripts/test_images.py)
set(TEST_IMAGE_INPUT_FILE ${PROJECT_SOURCE_DIR}/docs/test_images.txt)
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})

add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
COMMENT "Running doxygen"
VERBATIM)

add_custom_command(OUTPUT ${TEST_IMAGE_INDEX_FILE}
# run the test_images.py script with the PATH set
# to include the build's bin directory, to pick up
# the local bin/exrheader executable
COMMAND ${CMAKE_COMMAND} -E env "PATH=${CMAKE_CURRENT_BINARY_DIR}/../bin:$ENV{PATH}"
${Python3_EXECUTABLE} ${TEST_IMAGE_PY_FILE} ${OPENEXR_TEST_IMAGE_REPO} ${OPENEXR_TEST_IMAGE_TAG}
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
DEPENDS
${TEST_IMAGE_PY_FILE} ${TEST_IMAGE_INPUT_FILE}
COMMENT "Generating test image pages"
VERBATIM)

add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
COMMAND
${SPHINX_EXECUTABLE} -b html ${SPHINX_OPTS}
# Tell Breathe where to find the Doxygen output
-Dbreathe_projects.OpenEXR=${DOXYGEN_OUTPUT_DIR}/xml
${SPHINX_SOURCE} ${SPHINX_BUILD}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${DOXYGEN_INDEX_FILE} ${TEST_IMAGE_INDEX_FILE} ${TEST_IMAGE_PY_FILE} ${TEST_IMAGE_INPUT_FILE}
MAIN_DEPENDENCY ${SPHINX_CONF_PY_FILE}
COMMENT "Generating documentation with Sphinx")


# man pages for the bin programs

find_program(HELP2MAN help2man)

set(MANPAGE_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/man)
file(MAKE_DIRECTORY ${MANPAGE_OUTPUT_DIR}/man1)

message(STATUS "MANPAGE_OUTPUT_DIR=${MANPAGE_OUTPUT_DIR}")
message(STATUS "CMAKE_INSTALL_MANDIR=${CMAKE_INSTALL_MANDIR}")

set(manpage_files "")

function(DEFINE_MANPAGE tool description)
Expand Down Expand Up @@ -102,16 +45,10 @@ define_manpage(exrmultipart "combine or split multipart exr images")
define_manpage(exrmultiview "convert between single/multi-view exr images")
define_manpage(exrstdattr "set exr image metadata")

add_subdirectory(src)

add_custom_target(docs ALL DEPENDS
${SPHINX_INDEX_FILE}
${DOXYGEN_INDEX_FILE}
${TEST_IMAGE_INDEX_FILE}
${manpage_files}
${CMAKE_BINARY_DIR}/bin/docs_src)
${manpage_files})

# Add a target to install the manpages, but *not* the html
# Add a target to install the manpages

if(INSTALL_DOCS)
include(GNUInstallDirs)
Expand Down
11 changes: 0 additions & 11 deletions docs/src/CMakeLists.txt

This file was deleted.

2 changes: 1 addition & 1 deletion src/lib/IlmThread/IlmThreadExport.h
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

#include "OpenEXRConfig.h"

// See docs/SymbolVisibility.md for more discussion
// See website/SymbolVisibility.rst for more discussion

/// \addtogroup ExportMacros
/// @{
Expand Down
File renamed without changes.
69 changes: 69 additions & 0 deletions website/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# SPDX-License-Identifier: BSD-3-Clause
# Copyright Contributors to the OpenEXR Project.

set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})

find_package(Doxygen REQUIRED)
find_package(Sphinx REQUIRED)

include(FindPythonPackage)
find_python_package(sphinx-press-theme REQUIRED)

set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src/lib/OpenEXRCore)
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)

set(SPHINX_OPTS "-W" CACHE STRING "Sphinx build options")

set(OPENEXR_TEST_IMAGE_REPO "https://raw.githubusercontent.com/AcademySoftwareFoundation/openexr-images"
CACHE STRING "Repo for test images")
set(OPENEXR_TEST_IMAGE_TAG "main"
CACHE STRING "Tag for test image repo")

set(TEST_IMAGE_INDEX_FILE ${PROJECT_SOURCE_DIR}/website/_test_images/index.rst)
set(TEST_IMAGE_PY_FILE ${PROJECT_SOURCE_DIR}/website/scripts/test_images.py)
set(TEST_IMAGE_INPUT_FILE ${PROJECT_SOURCE_DIR}/website/test_images.txt)
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})

add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
COMMENT "Running doxygen"
VERBATIM)

add_custom_command(OUTPUT ${TEST_IMAGE_INDEX_FILE}
# run the test_images.py script with the PATH set
# to include the build's bin directory, to pick up
# the local bin/exrheader executable
COMMAND ${CMAKE_COMMAND} -E env "PATH=${CMAKE_CURRENT_BINARY_DIR}/../bin:$ENV{PATH}"
${Python3_EXECUTABLE} ${TEST_IMAGE_PY_FILE} ${OPENEXR_TEST_IMAGE_REPO} ${OPENEXR_TEST_IMAGE_TAG}
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
DEPENDS
${TEST_IMAGE_PY_FILE} ${TEST_IMAGE_INPUT_FILE}
COMMENT "Generating test image pages"
VERBATIM)

add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
COMMAND
${SPHINX_EXECUTABLE} -b html ${SPHINX_OPTS}
# Tell Breathe where to find the Doxygen output
-Dbreathe_projects.OpenEXR=${DOXYGEN_OUTPUT_DIR}/xml
${SPHINX_SOURCE} ${SPHINX_BUILD}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS ${DOXYGEN_INDEX_FILE} ${TEST_IMAGE_INDEX_FILE} ${TEST_IMAGE_PY_FILE} ${TEST_IMAGE_INPUT_FILE}
MAIN_DEPENDENCY ${SPHINX_CONF_PY_FILE}
COMMENT "Generating documentation with Sphinx")

add_custom_target(website ALL DEPENDS
${SPHINX_INDEX_FILE}
${DOXYGEN_INDEX_FILE}
${TEST_IMAGE_INDEX_FILE})

File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -1453,6 +1453,9 @@ access the data in the file directly, bypassing any copy operations
associated with reading the file via a C++ ``std::ifstream`` or a C
``FILE``.

Note that the following examples use POSIX memory mapping, not
supported on Windows.

Classes derived from ``IStream`` can optionally support memory-mapped
input. In order to do this, a derived class must override two virtual
functions, ``isMemoryMapped()`` and ``readMemoryMapped()``, in
Expand Down Expand Up @@ -1677,20 +1680,12 @@ subsampled.
Function ``makePreviewImage()`` calls ``gamma()`` to convert the
floating-point red, green, and blue components of the sampled main
image pixels to ``unsigned char`` values. ``gamma()`` is a simplified
version of what the exrdisplay program does in order to show an
OpenEXR image's floating-point pixels on the screen (for details, see
exrdisplay's source code):
version of what a program should do on order to show an OpenEXR
image's floating-point pixels on the screen:

.. code-block::
.. literalinclude:: src/gamma.cpp
:linenos:

unsigned char
gamma (float x)
{
x = pow (5.5555f * max (0.f, x), 0.4545f) * 84.66f;
return (unsigned char) clamp (x, 0.f, 255.f);
}

``makePreviewImage()`` converts the pixels' alpha component to
unsigned char by by linearly mapping the range ``[0.0, 1.0]`` to
``[0,255]``.
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes.
Loading