# ---------------------------------------------------------------------
# Code reference (Doxygen) — optional 'docs' target
#
# The output paths come from the top-level file, which defines them
# before adding this directory so that each is written in one place.
# ---------------------------------------------------------------------
option(DPM_DOCS_HTML "Generate the code reference in HTML" ON)
option(DPM_DOCS_PDF  "Generate the code reference as PDF (requires LaTeX)" ON)

find_package(Doxygen)
if(DOXYGEN_FOUND)
    # Doxygen and LaTeX both work in scratch space under docs/tmp. The
    # finished document is copied up into docs/, so the directory a user
    # opens holds documentation and nothing else.
    set(DOXYGEN_OUTPUT_DIRECTORY ${DPM_DOCS_TMP_DIR})
    set(DOXYGEN_EXTRACT_ALL YES)
    set(DOXYGEN_EXTRACT_STATIC YES)
    set(DOXYGEN_QUIET YES)
    set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
    set(DOXYGEN_JAVADOC_AUTOBRIEF YES)

    if(DPM_DOCS_HTML)
        set(DOXYGEN_GENERATE_HTML YES)
    else()
        set(DOXYGEN_GENERATE_HTML NO)
    endif()

    if(DPM_DOCS_PDF)
        set(DOXYGEN_GENERATE_LATEX YES)
        set(DOXYGEN_USE_PDFLATEX YES)
        set(DOXYGEN_PDF_HYPERLINKS YES)
    else()
        set(DOXYGEN_GENERATE_LATEX NO)
    endif()

    # The prose documents, each rendered as its own page in the generated
    # reference. Named one per line so the set of documents reaching the
    # output is stated here instead of implied by a directory.
    set(DPM_DOC_PAGES
            ${CMAKE_CURRENT_SOURCE_DIR}/PROSE/OVERVIEW.md
            ${CMAKE_CURRENT_SOURCE_DIR}/PROSE/DESIGN.md
            ${CMAKE_CURRENT_SOURCE_DIR}/PROSE/CONSUMERS.md
            ${CMAKE_CURRENT_SOURCE_DIR}/PROSE/MODULES.md
            ${CMAKE_CURRENT_SOURCE_DIR}/PROSE/BUILD.md
            ${CMAKE_CURRENT_SOURCE_DIR}/PROSE/DOCUMENTATION.md
    )

    # Two kinds of input: include/ and src/ supply the API and internals
    # reference extracted from the source, DPM_DOC_PAGES supplies the
    # prose pages.
    #
    # One target, so `cmake --build <dir> --target docs` is the whole
    # procedure and the IDE lists a single entry for it. The commands
    # below run after Doxygen and place the finished documents.
    doxygen_add_docs(docs
            ${CMAKE_SOURCE_DIR}/include
            ${CMAKE_SOURCE_DIR}/src
            ${DPM_DOC_PAGES}
            COMMENT "Generating the reference with Doxygen"
    )

    if(DPM_DOCS_PDF)
        find_program(PDFLATEX_EXECUTABLE pdflatex)
        if(PDFLATEX_EXECUTABLE)
            add_custom_command(TARGET docs POST_BUILD
                    COMMAND make -C ${DPM_DOCS_TMP_DIR}/latex
                    COMMAND ${CMAKE_COMMAND} -E rm -rf
                            ${DPM_DOCS_PDF_DIR}
                    COMMAND ${CMAKE_COMMAND} -E copy
                            ${DPM_DOCS_TMP_DIR}/latex/refman.pdf
                            ${DPM_DOCS_PDF_DIR}/dpm-core-${PROJECT_VERSION}.pdf
                    COMMENT "Compiling the PDF reference"
            )
        else()
            message(WARNING "DPM_DOCS_PDF is ON but pdflatex was not found; no PDF will be produced")
        endif()
    endif()

    if(DPM_DOCS_HTML)
        add_custom_command(TARGET docs POST_BUILD
                COMMAND ${CMAKE_COMMAND} -E rm -rf
                        ${DPM_DOCS_HTML_DIR}
                COMMAND ${CMAKE_COMMAND} -E copy_directory
                        ${DPM_DOCS_TMP_DIR}/html
                        ${DPM_DOCS_HTML_DIR}
                COMMENT "Placing the HTML reference"
        )
    endif()

    # Doxygen keeps output files it judges unchanged, so a run over a
    # populated scratch directory can carry pages forward from an earlier
    # one. Removing it here means the next run regenerates everything,
    # and leaves docs/ holding the finished documents alone.
    add_custom_command(TARGET docs POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E rm -rf ${DPM_DOCS_TMP_DIR}
            COMMENT "Clearing the generators' scratch directory"
    )
endif()