Commit 9bb8f1e2 authored by Simon Spannagel's avatar Simon Spannagel
Browse files

Merge branch 'p-api-reference-doxybook2' into 'master' 

docs: Doxygen via Doxybook2

See merge request allpix-squared/allpix-squared!813
parents 5a47f7e2 41cc9bb8

.gitlab-ci.yml

+7 −5
Original line number Diff line number Diff line
@@ -451,12 +451,14 @@ perf:cc7-gcc: 
# Compile Doxygen reference

docs:doxygen:

    extends: .doc

    image: gitlab-registry.cern.ch/sft/docker/centos7:latest

    image: $DOCKER_DEPS_IMAGE

    script:

        - source ../.ci/init_x86_64.sh

        - cmake -GNinja -DBUILD_DOCS_ONLY=ON ..

        - ninja apsq_docs_reference

        - mv doc/reference/html ../public/reference

        - apt install -y unzip doxygen

        - curl -sL https://github.com/matusnovak/doxybook2/releases/download/v1.5.0/doxybook2-linux-amd64-v1.5.0.zip --output /tmp/doxybook2-linux64.zip

        - unzip /tmp/doxybook2-linux64.zip -d /usr/local/

        - cmake -DBUILD_DOCS_ONLY=ON ..

        - make apsq_ref_markdown

        - mv doc/reference_markdown ../public/reference_markdown



# Create file tree for hugo

docs:usermanual-hugo:

cmake/Modules/FindDoxybook2.cmake

0 → 100644
+42 −0
Original line number Diff line number Diff line 
# SPDX-FileCopyrightText: 2022 CERN and the Allpix Squared authors

# SPDX-License-Identifier: MIT



# CMake script to find the doxybook2 executable and export it as Doxybook2::doxybook2 target



FIND_PROGRAM(

    DOXYBOOK2_EXECUTABLE

    NAMES doxybook2

)

MARK_AS_ADVANCED(DOXYBOOK2_EXECUTABLE)



IF(DOXYBOOK2_EXECUTABLE)

    EXECUTE_PROCESS(

        COMMAND "${DOXYBOOK2_EXECUTABLE}" "--version"

        OUTPUT_VARIABLE _Doxybook2_version

        OUTPUT_STRIP_TRAILING_WHITESPACE

        RESULT_VARIABLE _Doxybook2_version_result

        ERROR_QUIET)



    IF(_Doxybook2_version_result)

        MESSAGE(WARNING "Unable to determine doxybook2 version: ${_Doxybook2_version_result}")

    ELSE()

        # FIXME

        STRING(REGEX REPLACE "^v(.*)" "\\1" DOXYBOOK2_VERSION "${_Doxybook2_version}")

    ENDIF()



    IF(NOT TARGET Doxybook2::doxybook2)

        ADD_EXECUTABLE(Doxybook2::doxybook2 IMPORTED GLOBAL)

        SET_TARGET_PROPERTIES(Doxybook2::doxybook2 PROPERTIES

            IMPORTED_LOCATION "${DOXYBOOK2_EXECUTABLE}")

    ENDIF()

ENDIF()



IF(TARGET Doxybook2::doxybook2)

    SET(DOXYBOOK2_FOUND TRUE)

ENDIF()



INCLUDE(FindPackageHandleStandardArgs)

FIND_PACKAGE_HANDLE_STANDARD_ARGS(

    Doxybook2

    REQUIRED_VARS DOXYBOOK2_EXECUTABLE

    VERSION_VAR DOXYBOOK2_VERSION)

doc/CMakeLists.txt

+86 −52
Original line number Diff line number Diff line 
# SPDX-FileCopyrightText: 2016-2023 CERN and the Allpix Squared authors

# SPDX-License-Identifier: MIT



FIND_PACKAGE(Python COMPONENTS Interpreter)

IF(NOT PYTHON_FOUND)

    MESSAGE(WARNING "Could not find Python interpreter, no documentation generation possible")

    RETURN()

ENDIF()



############################################

# Doxygen target to generate API reference #

############################################
@@ -8,24 +14,44 @@ 
SET(DOCS_DOXYGEN_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/reference")



FIND_PACKAGE(Doxygen)



IF(DOXYGEN_FOUND)

    MESSAGE(STATUS "Docs: Adding target for reference generation with Doxygen")

    CONFIGURE_FILE("${CMAKE_CURRENT_SOURCE_DIR}/reference/Doxyfile" "${DOCS_DOXYGEN_BINARY_DIR}/Doxyfile" @ONLY)



    ADD_CUSTOM_TARGET(

    apsq_docs_reference

        apsq_ref_doxygen

        COMMAND Doxygen::doxygen "${DOCS_DOXYGEN_BINARY_DIR}/Doxyfile"

    DEPENDS Doxygen::doxygen

        WORKING_DIRECTORY "${DOCS_DOXYGEN_BINARY_DIR}"

        COMMENT "Generating API reference with Doxygen"

        VERBATIM)

    ADD_DEPENDENCIES(apsq_ref_doxygen Doxygen::doxygen Python::Interpreter)

ENDIF()



FIND_PACKAGE(Doxybook2)

IF(DOXYBOOK2_FOUND)

    MESSAGE(STATUS "Docs: Adding target for reference markdown generation")

    SET(REF_MARKDOWN_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/reference_markdown")

    ADD_CUSTOM_TARGET(

        apsq_ref_markdown

        COMMAND

            ${CMAKE_COMMAND} -E remove_directory -f ${REF_MARKDOWN_BINARY_DIR}

        COMMAND

            ${CMAKE_COMMAND} -E make_directory -f ${REF_MARKDOWN_BINARY_DIR}

        COMMAND

            Doxybook2::doxybook2 -q -i "${DOCS_DOXYGEN_BINARY_DIR}/xml" -o "${REF_MARKDOWN_BINARY_DIR}"

            -t "${CMAKE_CURRENT_SOURCE_DIR}/reference/doxybook"

            -c "${CMAKE_CURRENT_SOURCE_DIR}/reference/doxybook/config.json"

        DEPENDS apsq_ref_doxygen

        WORKING_DIRECTORY "${DOCS_DOXYGEN_BINARY_DIR}"

        COMMENT "Generating Markdown tree from Doxygen XML"

        VERBATIM)

    ADD_DEPENDENCIES(apsq_ref_markdown Doxybook2::doxybook2 Python::Interpreter)

ENDIF()



#######################################

# Target to create Markdown file tree #

#######################################



SET(DOCS_MARKDOWN_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/usermanual_markdown")



FIND_PACKAGE(Python COMPONENTS Interpreter)

SET(DOCS_PYTHON_HELPER "${CMAKE_CURRENT_SOURCE_DIR}/convert/cmake_helper.py")



ADD_CUSTOM_TARGET(
@@ -53,10 +79,10 @@ ADD_CUSTOM_TARGET( 
    COMMAND

        Python::Interpreter "-B" ${DOCS_PYTHON_HELPER} "copylower"

        "${DOCS_TESTS_CONF}" "${DOCS_MARKDOWN_BINARY_DIR}/15_appendix"

    DEPENDS Python::Interpreter

    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/convert"

    COMMENT "Generating source tree of the Markdown documentation"

    VERBATIM)

ADD_DEPENDENCIES(apsq_docs_markdown Python::Interpreter)



################################################

# Target to create Markdown file tree for hugo #
@@ -71,10 +97,11 @@ ADD_CUSTOM_TARGET( 
    COMMAND

        Python::Interpreter "-B" ${DOCS_PYTHON_HELPER} "convert_hugo"

        "${DOCS_MARKDOWN_BINARY_DIR}" "${DOCS_HUGO_BINARY_DIR}"

    DEPENDS Python::Interpreter apsq_docs_markdown

    DEPENDS apsq_docs_markdown

    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/convert"

    COMMENT "Generating source tree of the hugo documentation"

    VERBATIM)

ADD_DEPENDENCIES(apsq_docs_hugo Python::Interpreter)



############################################################

# Target to create LaTex file tree for the PDF user manual #
@@ -83,7 +110,8 @@ ADD_CUSTOM_TARGET( 
SET(DOCS_LATEX_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/usermanual_latex")



FIND_PACKAGE(Pandoc)



IF(PANDOC_FOUND)

    MESSAGE(STATUS "Docs: Adding target for user manual LaTeX generation")

    ADD_CUSTOM_TARGET(

        apsq_docs_latex

        COMMAND
@@ -91,10 +119,12 @@ ADD_CUSTOM_TARGET( 
        COMMAND

            Python::Interpreter "-B" ${DOCS_PYTHON_HELPER} "convert_latex"

            "${DOCS_MARKDOWN_BINARY_DIR}" "${DOCS_LATEX_BINARY_DIR}"

    DEPENDS Python::Interpreter Pandoc::pandoc apsq_docs_markdown

        DEPENDS apsq_docs_markdown

        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/convert"

        COMMENT "Generating source tree of the LaTeX documentation"

        VERBATIM)

    ADD_DEPENDENCIES(apsq_docs_latex Python::Interpreter Pandoc::pandoc)

ENDIF()



###############################################

# LaTeX target to compile the PDF user manual #
@@ -107,8 +137,9 @@ FIND_PACKAGE(Lualatex) 
FIND_PACKAGE(Biber)

FIND_PACKAGE(Pygmentize)



IF(LATEXMK_FOUND AND LUALATEX_FOUND AND BIBER_FOUND AND PYGMENTIZE_FOUND)

    MESSAGE(STATUS "Docs: Adding target for user manual PDF generation")

    SET(LATEXMK_COMPILER_FLAGS "-pdflua" "-cd" "-shell-escape")



    SET(DOCS_REFERENCES_BIB "${CMAKE_CURRENT_SOURCE_DIR}/latex/references.bib")

    SET(DOCS_ALLPIX_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/logo.png")

    CONFIGURE_FILE("${CMAKE_CURRENT_SOURCE_DIR}/latex/frontmatter.tex" "${CMAKE_CURRENT_BINARY_DIR}/frontmatter.tex" @ONLY)
@@ -129,7 +160,10 @@ ADD_CUSTOM_TARGET( 
        COMMAND

            ${CMAKE_COMMAND} -E rename "${DOCS_PDF_BINARY_DIR}/allpix-manual.pdf"

            "${DOCS_PDF_BINARY_DIR}/allpix-manual-${CPACK_PACKAGE_VERSION}.pdf"

    DEPENDS Python::Interpreter Latexmk::latexmk Lualatex::lualatex Biber::biber Pygmentize::pygmentize apsq_docs_latex

        DEPENDS apsq_docs_latex

        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/convert"

        COMMENT "Generating the PDF documentation"

        VERBATIM)

    ADD_DEPENDENCIES(

        apsq_docs_pdf Python::Interpreter Latexmk::latexmk Lualatex::lualatex Biber::biber Pygmentize::pygmentize)

ENDIF()

doc/convert/convert_markdown.py

+2 −1
Original line number Diff line number Diff line
@@ -250,7 +250,8 @@ def pandoc2latex(string: str, file_path: str, extra_args: list[str] = None) -> s 
    tmp.close()



    pandoc_args = [

        'pandoc', '-f', 'markdown+escaped_line_breaks+shortcut_reference_links+autolink_bare_uris+raw_html', '-t', 'latex',

        'pandoc', '-f', 'markdown+escaped_line_breaks+shortcut_reference_links+autolink_bare_uris+raw_html-raw_tex',

        '-t', 'latex',

        '--listings', '--biblatex',

        '--lua-filter', 'pandoc-gitlab-math.lua',

        '--lua-filter', 'pandoc-minted.lua',

doc/latex/allpix-manual.tex

+13 −0
Original line number Diff line number Diff line
@@ -48,6 +48,19 @@ 
% To fix warnings

\usepackage{scrhack}



% Fix deploying nested lists inherited from Doxygen

\usepackage{enumitem}

\setlistdepth{8}

\setlist[itemize,1]{label=$\bullet$}

\setlist[itemize,2]{label=$\bullet$}

\setlist[itemize,3]{label=$\bullet$}

\setlist[itemize,4]{label=$\bullet$}

\setlist[itemize,5]{label=$\bullet$}

\setlist[itemize,6]{label=$\bullet$}

\setlist[itemize,7]{label=$\bullet$}

\setlist[itemize,8]{label=$\bullet$}

\renewlist{itemize}{itemize}{8}



% Latin Modern fonts

\setmainfont{Latin Modern Roman}

\setsansfont{Latin Modern Sans}