mirror of
https://git.libssh.org/projects/libssh.git
synced 2025-12-06 13:20:57 +03:00
e5108f2ffc
Signed-off-by: Andreas Schneider <asn@cryptomilk.org> Reviewed-by: Jakub Jelen <jjelen@redhat.com>
226 lines
7.7 KiB
CMake
226 lines
7.7 KiB
CMake
#
|
|
# Build the documentation
|
|
#
|
|
# To build the documentation with a local doxygen-awesome-css tarball:
|
|
#
|
|
# cmake -S . -B obj \
|
|
# -DDOXYGEN_AWESOME_CSS_TARBALL=/path/to/doxygen-awesome-css.tar.gz cmake
|
|
# --build obj --target docs
|
|
#
|
|
# The tarball can be downloaded from:
|
|
# https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v2.4.1.tar.gz
|
|
#
|
|
find_package(Doxygen)
|
|
|
|
if (DOXYGEN_FOUND)
|
|
# Allow specifying a local tarball for doxygen-awesome-css (useful for
|
|
# packaging)
|
|
if (NOT DEFINED DOXYGEN_AWESOME_CSS_TARBALL)
|
|
set(DOXYGEN_AWESOME_CSS_TARBALL
|
|
"https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v2.4.1.tar.gz"
|
|
)
|
|
endif ()
|
|
|
|
include(FetchContent)
|
|
FetchContent_Declare(
|
|
doxygen-awesome-css URL ${DOXYGEN_AWESOME_CSS_TARBALL}
|
|
DOWNLOAD_EXTRACT_TIMESTAMP TRUE)
|
|
FetchContent_MakeAvailable(doxygen-awesome-css)
|
|
|
|
# Get the path to doxygen-awesome.css
|
|
FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)
|
|
|
|
# Project title shown in documentation
|
|
set(DOXYGEN_PROJECT_NAME ${PROJECT_NAME})
|
|
# Project version number shown in documentation
|
|
set(DOXYGEN_PROJECT_NUMBER ${PROJECT_VERSION})
|
|
# Brief description shown below project name
|
|
set(DOXYGEN_PROJECT_BRIEF "The SSH library")
|
|
# Project favicon (browser tab icon)
|
|
set(DOXYGEN_PROJECT_ICON ${CMAKE_CURRENT_SOURCE_DIR}/favicon.png)
|
|
|
|
# Number of spaces used for indentation in code blocks
|
|
set(DOXYGEN_TAB_SIZE 4)
|
|
# Generate output optimized for C (vs C++)
|
|
set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
|
|
# Enable parsing of markdown in comments
|
|
set(DOXYGEN_MARKDOWN_SUPPORT YES)
|
|
# Warn about undocumented members to improve documentation quality
|
|
set(DOXYGEN_WARN_IF_UNDOCUMENTED YES)
|
|
# Do not extract private class members
|
|
set(DOXYGEN_EXTRACT_PRIVATE NO)
|
|
# Do not include internal documentation
|
|
set(DOXYGEN_INTERNAL_DOCS NO)
|
|
# Disable built-in clipboard (using doxygen-awesome extension instead)
|
|
set(DOXYGEN_HTML_COPY_CLIPBOARD NO)
|
|
# Disable page outline panel (using interactive TOC extension instead)
|
|
set(DOXYGEN_PAGE_OUTLINE_PANEL NO)
|
|
|
|
# Required configuration for doxygen-awesome-css theme Generate treeview
|
|
# sidebar for navigation
|
|
set(DOXYGEN_GENERATE_TREEVIEW YES)
|
|
# Enable default index pages
|
|
set(DOXYGEN_DISABLE_INDEX NO)
|
|
# Use top navigation bar instead of full sidebar (required for theme
|
|
# compatibility)
|
|
set(DOXYGEN_FULL_SIDEBAR NO)
|
|
# Use light color style (required for Doxygen >= 1.9.5)
|
|
set(DOXYGEN_HTML_COLORSTYLE LIGHT)
|
|
|
|
# Disable diagram generation (not relevant for C projects)
|
|
set(DOXYGEN_HAVE_DOT NO)
|
|
set(DOXYGEN_CLASS_DIAGRAMS NO)
|
|
set(DOXYGEN_CALL_GRAPH NO)
|
|
set(DOXYGEN_CALLER_GRAPH NO)
|
|
|
|
# Preprocessor defines to use when parsing code
|
|
set(DOXYGEN_PREDEFINED DOXYGEN WITH_SERVER WITH_SFTP
|
|
PRINTF_ATTRIBUTE\(x,y\))
|
|
|
|
# Exclude patterns for files we don't want to document
|
|
set(DOXYGEN_EXCLUDE_PATTERNS */src/external/* fe25519.h ge25519.h sc25519.h
|
|
blf.h)
|
|
# Exclude internal structures from documentation
|
|
set(DOXYGEN_EXCLUDE_SYMBOLS_STRUCTS
|
|
chacha20_poly1305_keysched,
|
|
dh_ctx,
|
|
dh_ctx,
|
|
dh_keypair,
|
|
error_struct,
|
|
packet_struct,
|
|
pem_get_password_struct,
|
|
ssh_tokens_st,
|
|
sftp_attributes_struct,
|
|
sftp_client_message_struct,
|
|
sftp_dir_struct,
|
|
sftp_ext_struct,
|
|
sftp_file_struct,
|
|
sftp_message_struct,
|
|
sftp_packet_struct,
|
|
sftp_request_queue_struct,
|
|
sftp_session_struct,
|
|
sftp_status_message_struct,
|
|
ssh_agent_state_struct,
|
|
ssh_agent_struct,
|
|
ssh_auth_auto_state_struct,
|
|
ssh_auth_request,
|
|
ssh_bind_config_keyword_table_s,
|
|
ssh_bind_config_match_keyword_table_s,
|
|
ssh_bind_struct,
|
|
ssh_buffer_struct,
|
|
ssh_channel_callbacks_struct,
|
|
ssh_channel_read_termination_struct,
|
|
ssh_channel_request,
|
|
ssh_channel_request_open,
|
|
ssh_channel_struct,
|
|
ssh_cipher_struct,
|
|
ssh_common_struct,
|
|
ssh_config_keyword_table_s,
|
|
ssh_config_match_keyword_table_s,
|
|
ssh_connector_struct,
|
|
ssh_counter_struct,
|
|
ssh_crypto_struct,
|
|
ssh_event_fd_wrapper,
|
|
ssh_event_struct,
|
|
ssh_global_request,
|
|
ssh_gssapi_struct,
|
|
ssh_hmac_struct,
|
|
ssh_iterator,
|
|
ssh_kbdint_struct,
|
|
ssh_kex_struct,
|
|
ssh_key_struct,
|
|
ssh_knownhosts_entry,
|
|
ssh_list,
|
|
ssh_mac_ctx_struct,
|
|
ssh_message_struct,
|
|
ssh_packet_callbacks_struct,
|
|
ssh_packet_header,
|
|
ssh_poll_ctx_struct,
|
|
ssh_poll_handle_struct,
|
|
ssh_pollfd_struct,
|
|
ssh_private_key_struct,
|
|
ssh_public_key_struct,
|
|
ssh_scp_struct,
|
|
ssh_service_request,
|
|
ssh_session_struct,
|
|
ssh_signature_struct,
|
|
ssh_socket_struct,
|
|
ssh_string_struct,
|
|
ssh_threads_callbacks_struct,
|
|
ssh_timestamp)
|
|
set(DOXYGEN_EXCLUDE_SYMBOLS_MACRO
|
|
SSH_FXP*,
|
|
SSH_SOCKET*,
|
|
SERVERBANNER,
|
|
SOCKOPT_TYPE_ARG4,
|
|
SSH_FILEXFER*,
|
|
SSH_FXF*,
|
|
SSH_S_*,
|
|
SFTP_*,
|
|
NSS_BUFLEN_PASSWD,
|
|
CLOCK,
|
|
MAX_LINE_SIZE,
|
|
PKCS11_URI,
|
|
KNOWNHOSTS_MAXTYPES)
|
|
set(DOXYGEN_EXCLUDE_SYMBOLS_TYPEDEFS
|
|
sftp_attributes,
|
|
sftp_client_message,
|
|
sftp_dir,
|
|
sftp_ext,
|
|
sftp_file,
|
|
sftp_message,
|
|
sftp_packet,
|
|
sftp_request_queue,
|
|
sftp_session,
|
|
sftp_status_message,
|
|
sftp_statvfs_t,
|
|
poll_fn,
|
|
ssh_callback_int,
|
|
ssh_callback_data,
|
|
ssh_callback_int_int,
|
|
ssh_message_callback,
|
|
ssh_channel_callback_int,
|
|
ssh_channel_callback_data,
|
|
ssh_callbacks,
|
|
ssh_gssapi_select_oid_callback,
|
|
ssh_gssapi_accept_sec_ctx_callback,
|
|
ssh_gssapi_verify_mic_callback,
|
|
ssh_server_callbacks,
|
|
ssh_socket_callbacks,
|
|
ssh_packet_callbacks,
|
|
ssh_channel_callbacks,
|
|
ssh_bind,
|
|
ssh_bind_callbacks)
|
|
set(DOXYGEN_EXCLUDE_SYMBOLS
|
|
${DOXYGEN_EXCLUDE_SYMBOLS_STRUCTS} ${DOXYGEN_EXCLUDE_SYMBOLS_MACRO}
|
|
${DOXYGEN_EXCLUDE_SYMBOLS_TYPEDEFS})
|
|
|
|
# Custom layout file to rename "Topics" to "API Reference" and simplify
|
|
# navigation
|
|
set(DOXYGEN_LAYOUT_FILE ${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml)
|
|
# Custom HTML header with doxygen-awesome extension initialization
|
|
set(DOXYGEN_HTML_HEADER ${CMAKE_CURRENT_SOURCE_DIR}/header.html)
|
|
# Modern CSS theme for documentation with custom libssh.org color scheme
|
|
set(DOXYGEN_HTML_EXTRA_STYLESHEET
|
|
${AWESOME_CSS_DIR}/doxygen-awesome.css
|
|
${CMAKE_CURRENT_SOURCE_DIR}/doxygen-custom.css)
|
|
# JavaScript extensions: dark mode toggle, copy button, paragraph links,
|
|
# interactive TOC
|
|
set(DOXYGEN_HTML_EXTRA_FILES
|
|
${AWESOME_CSS_DIR}/doxygen-awesome-darkmode-toggle.js
|
|
${AWESOME_CSS_DIR}/doxygen-awesome-fragment-copy-button.js
|
|
${AWESOME_CSS_DIR}/doxygen-awesome-paragraph-link.js
|
|
${AWESOME_CSS_DIR}/doxygen-awesome-interactive-toc.js)
|
|
|
|
set(_doxyfile_template "${CMAKE_BINARY_DIR}/CMakeDoxyfile.in")
|
|
set(_target_doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.docs")
|
|
configure_file("${_doxyfile_template}" "${_target_doxyfile}")
|
|
|
|
doxygen_add_docs(docs ${CMAKE_SOURCE_DIR}/include/libssh
|
|
${CMAKE_SOURCE_DIR}/src ${CMAKE_CURRENT_SOURCE_DIR})
|
|
|
|
add_custom_target(
|
|
docs_coverage COMMAND ${CMAKE_SOURCE_DIR}/doc/doc_coverage.sh
|
|
${CMAKE_BINARY_DIR})
|
|
endif (DOXYGEN_FOUND)
|