#11776 - Publish All EnergyPlus Documentation Using ReadTheDocs

.github/workflows/build_documentation.yml

@@ -18,11 +18,13 @@ jobs:
       matrix:
         include:
           - os: ubuntu-24.04
-            generator: "Unix Makefiles"
+            generator: "Ninja"
             pretty: 'Ubuntu 24.04'
+            build_html: true
           - os: windows-2022
             generator: "Visual Studio 17 2022"
             pretty: "Windows"
+            build_html: false
 #         - os: macos-15
 #           generator: "Unix Makefiles"
 #           pretty: 'Mac arm64'
@@ -40,7 +42,11 @@ jobs:
 
     - name: Set up LaTeX on Linux
       if: runner.os == 'Linux'
-      run: sudo apt update && sudo apt install -y texlive texlive-xetex texlive-science poppler-utils
+      run: sudo apt update && sudo apt install -y texlive texlive-xetex texlive-science poppler-utils ninja-build
+
+    - name: Set up Pandoc on Linux
+      if: runner.os == 'Linux' && matrix.build_html
+      run: sudo apt install -y pandoc
 
     - name: Setup up LaTeX on Mac
       if: runner.os == 'macOS'
@@ -50,6 +56,10 @@ jobs:
         echo "/Library/TeX/texbin" >> $GITHUB_PATH
         brew install poppler
 
+    - name: Set up Pandoc on Mac
+      if: runner.os == 'macOS' && matrix.build_html
+      run: brew install pandoc
+
     - name: Set up LaTeX on Windows
       if: runner.os == 'Windows'
       run: |
@@ -111,6 +121,10 @@ jobs:
         fi;
         echo "TOC is available for pass NO.2"
 
+    - name: Set up Pandoc on Windows
+      if: runner.os == 'Windows' && matrix.build_html
+      run: choco install pandoc
+
     - name: Preinstall Packages on macOS
       if: runner.os == 'macOS'
       working-directory: ./doc/test
@@ -129,14 +143,16 @@ jobs:
 
     - name: Configure CMake
       working-directory: ./doc/build
-      run: cmake -G "${{ matrix.generator }}" -DTEX_INTERACTION=batchmode -DDOCS_TESTING=ON ..
+      run: |
+        cmake -G "${{ matrix.generator }}" -DTEX_INTERACTION=batchmode -DDOCS_TESTING=ON \
+          ${{ matrix.build_html && '-DBUILD_HTML_DOCS:BOOL=ON' || '' }} ..
 
     - name: Add problem matcher
       run: echo "::add-matcher::.github/workflows/doc-problem-match.json"
 
     - name: Build Docs
       working-directory: ./doc/build
-      run: cmake --build . -j 4
+      run: cmake --build . --target docs -j 4
 
     - name: Upload EngineeringReference
       uses: actions/upload-artifact@v7
@@ -208,6 +224,20 @@ jobs:
         name: "AllDocumentation-${{ matrix.os }}-${{ github.event.pull_request.head.sha }}"
         path: ${{ github.workspace }}/doc/build/pdf/
 
+    - name: Build HTML Docs
+      if: matrix.build_html
+      working-directory: ./doc/build
+      run: |
+        ninja html_docs
+        tar -czf html.tar.gz -C html .
+
+    - name: Upload HTML documentation
+      uses: actions/upload-artifact@v7
+      if: matrix.build_html
+      with:
+        name: "HtmlDocumentation-${{ matrix.os }}-${{ github.event.pull_request.head.sha }}"
+        path: ${{ github.workspace }}/doc/build/html.tar.gz
+
     - name: Upload log folder upon failure
       if: failure() && runner.os == 'Windows'
       uses: actions/upload-artifact@v7

.gitignore

@@ -52,8 +52,7 @@ doc/title.tex
 
 # ignore the doxygen and sphinx built API docs
 doc/readthedocs/doxygen/_build
-doc/readthedocs/sphinx/_build
-doc/readthedocs/sphinx/_build_c
+doc/readthedocs/sphinx/_build*
 /doc/readthedocs/sphinx/schema.rst
 
 # now that we have python, ignore some things

.readthedocs.yml

@@ -10,6 +10,18 @@ build:
     python: "3.11"
   apt_packages:
     - doxygen
+    - cmake
+    - texlive-xetex
+  jobs:
+    pre_build:
+      - bash doc/readthedocs/install_pandoc.sh "$READTHEDOCS_OUTPUT/tools"
+    post_build:
+      # Build the pandoc-based chunked HTML guides (Engineering Reference, I/O Reference, etc.)
+      # and publish them alongside the Sphinx runtime/API docs.
+      - cmake -S doc -B doc/build -DBUILD_HTML_DOCS:BOOL=ON -DPANDOC="$READTHEDOCS_OUTPUT/tools/pandoc-3.11/bin/pandoc"
+      - cmake --build doc/build --target html_docs -j 4
+      - mkdir -p "$READTHEDOCS_OUTPUT/html/guides"
+      - cp -r doc/build/html/. "$READTHEDOCS_OUTPUT/html/guides/"
 
 python:
   install:

README.md

@@ -36,20 +36,30 @@ Iteration **(pre-)releases** may be created during a development cycle, however
 If an interim release is intended for active use by users, such as a bug-fix-only or performance-only re-release, it will be clearly specified on the release notes and a public announcement will accompany this type of release.
 Our releases are now built by GitHub Actions.
 
-## Core Documentation
-
-Program documentation is installed alongside the program, with the pdfs also available [online](https://energyplus.net/documentation).
-Big Ladder also produces html based documentation [online](http://bigladdersoftware.com/epx/docs/).
-
-## API Documentation
+## Documentation
 
 [![Read the Docs](https://img.shields.io/readthedocs/energyplus?label=docs%20%28latest%29&color=5AC451)](https://energyplus.readthedocs.io/en/latest/)
 [![Read the Docs](https://img.shields.io/readthedocs/energyplus?label=docs%20%28stable%29&color=5AC451)](https://energyplus.readthedocs.io/en/stable/)
 
-An API has been developed to allow access to internal EnergyPlus functionality and open up the possibility for new workflow opportunities around EnergyPlus.
-A C API is developed to expose the C++ functions, then Python bindings are built on top of that to maximize the accessibility.
-Documentation is being built and posted on ReadTheDocs and that documentation will continue to be expanded over time as the API grows.
-The badges above here show the status, and link out to, the `latest` documentation (most recent commit to the `develop` branch) as well as the `stable` documentation (most recent release tag).
+The [EnergyPlus documentation site](https://energyplus.readthedocs.io/en/latest/) brings together
+introductory material, user and developer guides, input-schema documentation, and the C and Python
+API references. Start with the [Quick Start Guide](https://energyplus.readthedocs.io/en/latest/quick_start/quick_start.html)
+to install EnergyPlus and run a first simulation, or browse the complete documentation for detailed
+modeling and development guidance.
+
+Key references include:
+
+- [Getting Started](https://energyplus.readthedocs.io/en/latest/guides/getting-started/index.html) —  a comprehensive introduction to EnergyPlus concepts, workflows, input files, and output files.
+- [Input Output Reference](https://energyplus.readthedocs.io/en/latest/guides/input-output-reference/index.html) —  an encyclopedic reference to EnergyPlus input objects and output reports.
+- [Engineering Reference](https://energyplus.readthedocs.io/en/latest/guides/engineering-reference/index.html) —  the theoretical background, algorithms, and calculation methods used by EnergyPlus.
+- [EnergyPlus epJSON input schema](https://energyplus.readthedocs.io/en/latest/schema.html) —  searchable definitions for EnergyPlus input objects and fields.
+- [C API reference](https://energyplus.readthedocs.io/en/latest/c.html) — the native API for embedding EnergyPlus and accessing runtime, data-transfer, functional, and callback interfaces.
+- [Python API reference](https://energyplus.readthedocs.io/en/latest/api.html) — Python bindings for the EnergyPlus C API and supporting functionality.
+
+The [`latest`](https://energyplus.readthedocs.io/en/latest/) documentation follows the `develop` branch, while [`stable`](https://energyplus.readthedocs.io/en/stable/) follows the most recent release.
+PDF documentation is also included with the packages on the [EnergyPlus releases page](https://github.com/NatLabRockies/EnergyPlus/releases). Big Ladder maintains an independent [archive of web-based EnergyPlus documentation](https://bigladdersoftware.com/epx/docs/) for released versions.
+
+For local build instructions and information about contributing documentation, see the [documentation contributor guide](doc/readthedocs/README.md).
 
 ## License & Contributing Development
 

doc/.gitignore

@@ -53,3 +53,6 @@
 *.nlo
 
 # Texpad
+
+*/chunked/*
+*/single_dir/*

doc/CMakeLists.txt

@@ -16,6 +16,15 @@ endif()
 
 find_package(LATEX COMPONENTS XELATEX)
 
+option(BUILD_HTML_DOCS "Also build paginated HTML documentation (requires pandoc)" OFF)
+
+if(BUILD_HTML_DOCS)
+  find_program(PANDOC NAMES pandoc)
+  if(NOT PANDOC)
+    message(FATAL_ERROR "BUILD_HTML_DOCS is ON but pandoc was not found in PATH")
+  endif()
+endif()
+
 set(TEX_INTERACTION
     "batchmode"
     CACHE STRING "Choose the interaction mode for TeX.")
@@ -42,6 +51,23 @@ if(EXISTS "${XELATEX_COMPILER}")
 
   set_target_properties(docs PROPERTIES FOLDER Documentation)
 
+  if(BUILD_HTML_DOCS)
+    file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/html)
+    file(COPY ${PROJECT_SOURCE_DIR}/html/index.html ${PROJECT_SOURCE_DIR}/html/style.css ${PROJECT_SOURCE_DIR}/html/media
+      DESTINATION ${PROJECT_BINARY_DIR}/html)
+
+    # Aggregate target: depends on each individual zHTML_<doc> target added via create_html_doc_target
+    if(hasParent AND BUILD_DOCS_ONLY_WITH_PACKAGE)
+      # Because we don't want to rebuild doc automatically, we do not add it to the 'ALL' rule
+      message(STATUS "The target `html_docs` was added, but not to the default build rule. It will be triggered by `make html_docs` or `make package`")
+      add_custom_target(html_docs)
+    else()
+      # Building standalone, so add to ALL
+      add_custom_target(html_docs ALL)
+    endif()
+    set_target_properties(html_docs PROPERTIES FOLDER Documentation)
+  endif()
+
   include(cmake/doc-targets.cmake)
 
   # add each of the documents, they have their own CMakeLists.txt files

doc/cmake/BuildHtmlDocumentation.cmake

@@ -0,0 +1,79 @@
+# Caller needs to set:
+  # PANDOC, the path to the pandoc executable
+  # INNAME, the name of the input tex file (without extension)
+  # OUTNAME, the directory name to use under html/ in the build tree (eg "input-output-reference")
+  # HTML_ASSETS_DIR, the doc/html directory holding the shared templates/css/lua filters
+  # ORIGINAL_CMAKE_SOURCE_DIR, the root of the source repo (doc/)
+  # ORIGINAL_CMAKE_BINARY_DIR, the root of the build tree (doc/'s binary dir)
+  # Python_EXECUTABLE, used to build the search index from pandoc's sitemap.json
+
+set(COMMAND_ECHO_MODE NONE)
+
+if(WIN32)
+  set(TEXINPUTS_SEPARATOR ";")
+else()
+  set(TEXINPUTS_SEPARATOR ":")
+endif()
+set(ENV{TEXINPUTS} "${ORIGINAL_CMAKE_BINARY_DIR}${TEXINPUTS_SEPARATOR}$ENV{TEXINPUTS}")
+
+set(HTML_OUT_DIR "${ORIGINAL_CMAKE_BINARY_DIR}/html/${OUTNAME}")
+
+file(REMOVE_RECURSE "${HTML_OUT_DIR}")
+
+# Pandoc versions used by local development and Read the Docs do not expose the
+# same MathML option. Prefer the current spelling when available, while retaining
+# compatibility with older Pandoc releases.
+execute_process(
+  COMMAND "${PANDOC}" --help
+  OUTPUT_VARIABLE PANDOC_HELP
+  ERROR_QUIET
+  RESULT_VARIABLE PANDOC_HELP_RESULT
+)
+
+if(PANDOC_HELP_RESULT EQUAL 0 AND PANDOC_HELP MATCHES "--math-method")
+  set(PANDOC_MATHML_OPTION "--math-method=mathml")
+else()
+  set(PANDOC_MATHML_OPTION "--mathml")
+endif()
+
+execute_process(
+  COMMAND "${PANDOC}"
+          --to=chunkedhtml
+          ${PANDOC_MATHML_OPTION}
+          --standalone
+          --table-of-contents
+          --split-level=2
+          --metadata=doc-class:${OUTNAME}
+          --output=${HTML_OUT_DIR}
+          --template=${HTML_ASSETS_DIR}/template_chunked.html
+          --css=style.css
+          --include-in-header=${HTML_ASSETS_DIR}/header.html
+          --include-after-body=${HTML_ASSETS_DIR}/footer.html
+          --lua-filter=${HTML_ASSETS_DIR}/bootstrap-tables.lua
+          --lua-filter=${HTML_ASSETS_DIR}/numbered-cross-references.lua
+          --lua-filter=${HTML_ASSETS_DIR}/object-index.lua
+          ${INNAME}.tex
+  RESULT_VARIABLE ERRCODE
+  COMMAND_ECHO ${COMMAND_ECHO_MODE}
+)
+
+if(NOT ERRCODE EQUAL 0)
+  message(FATAL_ERROR "pandoc failed to build the HTML documentation for ${INNAME} (error code ${ERRCODE})")
+endif()
+
+# Build search index from sitemap (levels 2, 3 & 5: groups, objects, field names)
+execute_process(
+  COMMAND "${Python_EXECUTABLE}" "${ORIGINAL_CMAKE_SOURCE_DIR}/cmake/build_search_index.py"
+          "${HTML_OUT_DIR}/sitemap.json" "${HTML_OUT_DIR}/search-index.js"
+  RESULT_VARIABLE ERRCODE
+  COMMAND_ECHO ${COMMAND_ECHO_MODE}
+)
+
+if(NOT ERRCODE EQUAL 0)
+  message(FATAL_ERROR "Failed to build the search index for ${INNAME} (error code ${ERRCODE})")
+endif()
+
+# Copy assets that pandoc doesn't copy for chunked output
+file(COPY "${HTML_ASSETS_DIR}/style.css" DESTINATION "${HTML_OUT_DIR}")
+file(MAKE_DIRECTORY "${HTML_OUT_DIR}/media")
+file(COPY "${ORIGINAL_CMAKE_SOURCE_DIR}/../release/ep_nobg.png" DESTINATION "${HTML_OUT_DIR}/media")

doc/cmake/build_search_index.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+# EnergyPlus, Copyright (c) 1996-present, The Board of Trustees of the
+# University of Illinois, The Regents of the University of California, through
+# Lawrence Berkeley National Laboratory (subject to receipt of any required
+# approvals from the U.S. Dept. of Energy), Oak Ridge National Laboratory,
+# managed by UT-Battelle, Alliance for Energy Innovation, LLC, and other
+# contributors. All rights reserved.
+#
+# NOTICE: This Software was developed under funding from the U.S. Department of
+# Energy and the U.S. Government consequently retains certain rights. As such,
+# the U.S. Government has been granted for itself and others acting on its
+# behalf a paid-up, nonexclusive, irrevocable, worldwide license in the
+# Software to reproduce, distribute copies to the public, prepare derivative
+# works, and perform publicly and display publicly, and to permit others to do
+# so.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# (1) Redistributions of source code must retain the above copyright notice,
+#     this list of conditions and the following disclaimer.
+#
+# (2) Redistributions in binary form must reproduce the above copyright notice,
+#     this list of conditions and the following disclaimer in the documentation
+#     and/or other materials provided with the distribution.
+#
+# (3) Neither the name of the University of California, Lawrence Berkeley
+#     National Laboratory, the University of Illinois, U.S. Dept. of Energy nor
+#     the names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+# (4) Use of EnergyPlus(TM) Name. If Licensee (i) distributes the software in
+#     stand-alone form without changes from the version obtained under this
+#     License, or (ii) Licensee makes a reference solely to the software
+#     portion of its product, Licensee must refer to the software as
+#     "EnergyPlus version X" software, where "X" is the version number Licensee
+#     obtained under this License and may not use a different name for the
+#     software. Except as specifically required in this Section (4), Licensee
+#     shall not use in a company name, a product name, in advertising,
+#     publicity, or other promotional activities any name, trade name,
+#     trademark, logo, or other designation of "EnergyPlus", "E+", "e+" or
+#     confusingly similar designation, without the U.S. Department of Energy's
+#     prior written consent.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""Build a search-index.js file from a pandoc chunkedhtml sitemap.json.
+
+Usage: build_search_index.py <sitemap.json> <search-index.js>
+"""
+import argparse
+import json
+import pathlib
+
+
+def collect(node, out):
+    section = node["section"]
+    if int(section["level"]) in (2, 3, 5):
+        out.append({"t": section["title"], "p": section["path"]})
+    for sub in node.get("subsections", []):
+        collect(sub, out)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("sitemap", type=pathlib.Path, help="Path to pandoc's sitemap.json")
+    parser.add_argument("output", type=pathlib.Path, help="Path to write search-index.js to")
+    args = parser.parse_args()
+
+    index = []
+    collect(json.loads(args.sitemap.read_text()), index)
+    args.output.write_text("window.SEARCH_INDEX=" + json.dumps(index) + ";")
+
+
+if __name__ == "__main__":
+    main()