diff --git a/CMakeLists.txt b/CMakeLists.txt index 1299a7c1a5..09a6c54c62 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -121,3 +121,8 @@ endif() if(NOT OPENEXR_IS_SUBPROJECT) include(cmake/clang-format.cmake) endif() + +option(DOCS "Set ON to build html documentation") +if (DOCS) + add_subdirectory(docs) +endif() diff --git a/INSTALL.md b/INSTALL.md index 6fa3bf9e60..f9f60b69b6 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -71,7 +71,7 @@ can specify a local install directory to cmake via the % cmake .. -DCMAKE_INSTALL_PREFIX=$install_directory -## Porting Application from OpenEXR v2 to v3 +## Porting Applications from OpenEXR v2 to v3 See the [porting guide](https://github.com/AcademySoftwareFoundation/Imath/blob/master/docs/PortingGuide2-3.md) @@ -79,6 +79,28 @@ for details about differences from previous releases and how to address them. Also refer to the porting guide for details about changes to Imath. +## Documentation + +The OpenEXR technical documentation at +[openexr.readthedocs.io](https://openexr.readthedocs.io) is generated +via [Sphinx](https://www.sphinx-doc.org) with the +[Breathe](https://breathe.readthedocs.io) extension using information +extracted from header comments by [Doxgen](https://www.doxygen.nl). + +To build the documentation locally from the source headers and +``.rst`` files, set the CMake option ``DOCS=ON``. This adds +``Doxygen`` and ``Sphinx`` CMake targets. Local documentation +generation is off by default. + +Building the documentation requires that sphinx, breathe, and doxygen +are installed. + +Note that the [openexr.readthedocs.io](https://openexr.readthedocs.io) +documentation takes the place of the formerly distributed .pdf +documents in the ``docs`` folder, although readthedocs supports +downloading of documentation in pdf format, for those who prefer it +that way. + ## Library Names By default the installed libraries follow a pattern for how they are diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake new file mode 100644 index 0000000000..89640a59a1 --- /dev/null +++ b/cmake/FindSphinx.cmake @@ -0,0 +1,12 @@ +#Look for an executable called sphinx-build +find_program(SPHINX_EXECUTABLE + NAMES sphinx-build + DOC "Path to sphinx-build executable") + +include(FindPackageHandleStandardArgs) + +#Handle standard arguments to find_package like REQUIRED and QUIET +find_package_handle_standard_args(Sphinx + "Failed to find sphinx-build executable" + SPHINX_EXECUTABLE) + diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000000..0b24348b73 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,47 @@ +# 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) + +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) + +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_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE}) + +add_custom_command(OUTPUT ${SPHINX_INDEX_FILE} + COMMAND + ${SPHINX_EXECUTABLE} -b html + # 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} + MAIN_DEPENDENCY conf.py + COMMENT "Generating documentation with Sphinx") + +add_custom_target(Sphinx ALL DEPENDS ${SPHINX_INDEX_FILE}) + +# Add an install target to install the docs +include(GNUInstallDirs) +install(DIRECTORY ${SPHINX_BUILD} +DESTINATION ${CMAKE_INSTALL_DOCDIR}) diff --git a/docs/Doxyfile b/docs/Doxyfile.in similarity index 91% rename from docs/Doxyfile rename to docs/Doxyfile.in index b4057eb840..1ef4bcaaac 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile.in @@ -1,10 +1,10 @@ PROJECT_NAME = "OpenEXR" -XML_OUTPUT = doxyxml GENERATE_LATEX = NO GENERATE_MAN = NO GENERATE_RTF = NO CASE_SENSE_NAMES = NO -INPUT = ../src/lib +INPUT = "@DOXYGEN_INPUT_DIR@" +OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@" RECURSIVE = YES QUIET = YES JAVADOC_AUTOBRIEF = YES @@ -38,5 +38,5 @@ PREDEFINED = \ IMF_EXPORT_ENUM="" \ IMF_EXPORT_TEMPLATE_TYPE="" \ IMF_EXPORT_TEMPLATE_INSTANCE="" \ - OPENEXR_EXPORT="" - \ No newline at end of file + OPENEXR_EXPORT="" \ + EXR_EXPORT="" diff --git a/docs/conf.py b/docs/conf.py index ac1eee4503..5116b678db 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,8 +23,20 @@ # hack for readthedocs to cause it to run doxygen first # https://github.com/rtfd/readthedocs.org/issues/388 + on_rtd = os.environ.get('READTHEDOCS', None) == 'True' if on_rtd: + + with open("Doxyfile.in", "r") as file: + filedata = file.read() + + doxygen_output_dir = "_build" + filedata = filedata.replace('@DOXYGEN_INPUT_DIR@', "../src/lib/OpenEXRCore") + filedata = filedata.replace('@DOXYGEN_OUTPUT_DIR@', "doxygen") + + with open("Doxyfile", "w") as file: + file.write(filedata) + from subprocess import call call('doxygen') @@ -44,7 +56,7 @@ ] # Breathe extension variables -breathe_projects = { "OpenEXR": "doxyxml/" } +breathe_projects = { "OpenEXR": "doxygen/xml" } breathe_default_project = "OpenEXR" # Add any paths that contain templates here, relative to this directory. @@ -67,10 +79,19 @@ # |version| and |release|, also used in various other places throughout the # built documents. # +project_OpenEXR_VERSION = "project(OpenEXR VERSION " +release = None +for l in open ("../CMakeLists.txt"): + if l.startswith (project_OpenEXR_VERSION): + release = l.split (' ')[2] + break +if release == None: + print ("Error in conf.py: can't find OpenEXR VERSION in ../CMakeList.txt") + exit(-1) + +v = release.split('.') # The short X.Y version. -version = '3.1' -# The full version, including alpha/beta/rc tags. -release = '3.1.0' +version = "%s.%s" % (v[0], v[1]) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -148,7 +169,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -157,11 +178,11 @@ # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} @@ -218,7 +239,7 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ ('index', 'OpenEXR.tex', 'OpenEXR Documentation', - 'Cary Phillips', 'manual'), + 'Contributors to the OpenEXR Project', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -248,7 +269,7 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'imath', 'OpenEXR Documentation', - ['Cary Phillips'], 1) + ['Contributors to the OpenEXR Project'], 1) ] # If true, show URL addresses after external links. @@ -262,7 +283,7 @@ # dir menu entry, description, category) texinfo_documents = [ ('index', 'OpenEXR', 'OpenEXR Documentation', - 'Cary Phillips', 'OpenEXR', 'One line description of project.', + 'Contributors to the OpenEXR Project', 'OpenEXR', 'Professional-grade image storage format', 'Miscellaneous'), ]