Generate documentation using the FindSphinx.cmake module
Signed-off-by: Jeroen Koekkoek <jeroen@koekkoek.nl>
This commit is contained in:
Jeroen Koekkoek
parent
9cf4b97f1a
commit
b916f0bfb7
23 changed files with 151 additions and 3503 deletions
|
|
@ -8,42 +8,5 @@
|
|||
# http://www.eclipse.org/org/documents/edl-v10.php.
|
||||
#
|
||||
# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
|
||||
add_subdirectory(manual)
|
||||
|
||||
# TODO depending on requirements we can add/remove options as needed,
|
||||
# these are examples of generators we'll need as a minimum.
|
||||
# Perhaps we should also consider options for building subset of all docs.
|
||||
# When a certain doc is related to a target, no option is needed; you can simply check if the target exists
|
||||
# (i.e. if a target 'ddsc' exists, build ddsc api docs). And possibly make the target definition dependent on an option.
|
||||
|
||||
find_program(SPHINX_EXECUTABLE NAMES sphinx-build DOC "Sphinx documentation builder")
|
||||
if (NOT SPHINX_EXECUTABLE)
|
||||
message(FATAL_ERROR "${CMAKE_PROJECT_NAME} documentation: unable to find sphinx-build executable")
|
||||
endif()
|
||||
|
||||
find_package(Doxygen)
|
||||
if (NOT Doxygen_FOUND)
|
||||
message(FATAL_ERROR "${CMAKE_PROJECT_NAME} documentation: unable to find Doxygen")
|
||||
endif()
|
||||
|
||||
# Creating pdf from latex requires latexmk (which depends on perl, latexpdf et. al)
|
||||
find_program(LATEXMK_EXECUTABLE NAMES latexmk DOC "LateX PDF Generator")
|
||||
if (NOT LATEXMK_EXECUTABLE)
|
||||
message(FATAL_ERROR "${CMAKE_PROJECT_NAME} documentation: unable to find latexmk")
|
||||
endif()
|
||||
|
||||
if (SPHINX_EXECUTABLE AND Doxygen_FOUND AND LATEXMK_EXECUTABLE)
|
||||
set(BUILD_DOCS ON PARENT_SCOPE) # for examples' docs
|
||||
set(BUILD_DOCS ON)
|
||||
message(STATUS "${CMAKE_PROJECT_NAME} documentation: Success (build)")
|
||||
endif()
|
||||
|
||||
if(BUILD_DOCS)
|
||||
add_subdirectory(manual)
|
||||
endif()
|
||||
|
||||
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
|
||||
DESTINATION ${CMAKE_INSTALL_DOCDIR}
|
||||
COMPONENT dev)
|
||||
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}.pdf
|
||||
DESTINATION ${CMAKE_INSTALL_DOCDIR}
|
||||
COMPONENT dev)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
#
|
||||
# Copyright(c) 2006 to 2018 ADLINK Technology Limited and others
|
||||
# Copyright(c) 2006 to 2019 ADLINK Technology Limited and others
|
||||
#
|
||||
# This program and the accompanying materials are made available under the
|
||||
# terms of the Eclipse Public License v. 2.0 which is available at
|
||||
|
|
@ -8,115 +8,16 @@
|
|||
# http://www.eclipse.org/org/documents/edl-v10.php.
|
||||
#
|
||||
# SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
|
||||
|
||||
# TODO depending on requirements we can add/remove options as needed,
|
||||
# these are examples of generators we'll need as a minimum.
|
||||
# Perhaps we should also consider options for building subset of all docs.
|
||||
# When a certain doc is related to a target, no option is needed; you can simply check if the target exists
|
||||
# (i.e. if a target 'ddsc' exists, build ddsc api docs). And possibly make the target definition dependent on an option.
|
||||
|
||||
# Generate ddsc API docs in XML format using Doxygen, if the ddsc target is defined.
|
||||
# The XML will serve as input for sphinx' breathe plugin
|
||||
if (TARGET ${CMAKE_PROJECT_NAME}::ddsc)
|
||||
# Process doxygen configuration file, for ddsc
|
||||
set(doxy_conf_project "${CMAKE_PROJECT_NAME_FULL} C API Documentation")
|
||||
set(doxy_conf_outputdir "ddsc_api")
|
||||
set(doxy_conf_input "${PROJECT_SOURCE_DIR}/src/core/ddsc/include/dds/dds.h ${PROJECT_SOURCE_DIR}/src/core/ddsc/include/dds")
|
||||
configure_file(Doxyfile.in Doxyfile @ONLY)
|
||||
|
||||
add_custom_target(ddsc_docs
|
||||
${DOXYGEN_EXECUTABLE} Doxyfile
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Running Doxygen for API docs generation"
|
||||
VERBATIM)
|
||||
|
||||
# Remove generated files when cleaning the build tree
|
||||
set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${doxy_conf_outputdir})
|
||||
|
||||
# Add ddsc api docs to sphinx' breathe projects
|
||||
set(sph_conf_breathe_projs "\"ddsc_api\": \"${doxy_conf_outputdir}/xml\"")
|
||||
|
||||
add_custom_command(TARGET ddsc_docs
|
||||
POST_BUILD
|
||||
WORKING_DIRECTORY "${doxy_conf_outputdir}"
|
||||
COMMAND ${CMAKE_COMMAND} -E tar "zcf" "${CMAKE_PROJECT_NAME}_C_HTML.tar.gz" "ddsc")
|
||||
if(BUILD_DOCS)
|
||||
find_package(Sphinx REQUIRED breathe)
|
||||
sphinx_add_docs(
|
||||
docs
|
||||
BREATHE_PROJECTS ddsc_api_docs
|
||||
BUILDER html
|
||||
SOURCE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
|
||||
install(
|
||||
DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/docs/"
|
||||
DESTINATION "${CMAKE_INSTALL_DOCDIR}/manual"
|
||||
COMPONENT dev)
|
||||
endif()
|
||||
|
||||
# Process sphinx configuration file
|
||||
set(sph_conf_author "Eclipse Cyclone DDS project")
|
||||
set(sph_conf_version "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")
|
||||
set(sph_conf_release "${PROJECT_VERSION}")
|
||||
configure_file(conf.py.in conf.py @ONLY)
|
||||
|
||||
# Define a list of output formats (-b option for sphinx-build)
|
||||
set(docs_builders "")
|
||||
list(APPEND docs_builders html)
|
||||
list(APPEND docs_builders latex)
|
||||
|
||||
# Define custom commands for running sphinx-build for different docs builders
|
||||
set(docs_outputs "")
|
||||
foreach(builder ${docs_builders})
|
||||
set(docs_builder_output "docs_${builder}_output")
|
||||
# Log stdout (not stderr) to a file instead of messing up build output
|
||||
set(docs_builder_log "sphinx-build-${builder}.log")
|
||||
|
||||
add_custom_command(OUTPUT ${docs_builder_output}
|
||||
COMMAND ${SPHINX_EXECUTABLE}
|
||||
-b ${builder}
|
||||
-d ${CMAKE_CURRENT_BINARY_DIR}/cache
|
||||
-c ${CMAKE_CURRENT_BINARY_DIR}
|
||||
${PROJECT_SOURCE_DIR}/docs/manual
|
||||
${CMAKE_CURRENT_BINARY_DIR}/${builder} > ${docs_builder_log}
|
||||
COMMENT "Running Sphinx for ${builder} output"
|
||||
VERBATIM)
|
||||
|
||||
# FIXME: This is definitely in the wrong location
|
||||
if(builder STREQUAL html)
|
||||
add_custom_command(OUTPUT ${docs_builder_output}
|
||||
COMMAND ${CMAKE_COMMAND}
|
||||
-E tar "zcf"
|
||||
"${CMAKE_PROJECT_NAME}HTML.tar.gz"
|
||||
"html"
|
||||
APPEND
|
||||
VERBATIM)
|
||||
endif()
|
||||
|
||||
# Create a pdf from the latex builder output, by appending a latexmk command
|
||||
# TODO look into rinohtype as an alternative (don't bother with rst2pdf, it's no good)
|
||||
if(builder STREQUAL latex)
|
||||
add_custom_command(OUTPUT ${docs_builder_output}
|
||||
COMMAND ${LATEXMK_EXECUTABLE}
|
||||
-interaction=nonstopmode
|
||||
-silent
|
||||
-output-directory=${builder}
|
||||
-pdf -dvi- -ps- -cd- ${builder}/${CMAKE_PROJECT_NAME}.tex
|
||||
APPEND
|
||||
VERBATIM)
|
||||
|
||||
# Move the pdf, so that install rules don't need to differentiate between built and downloaded docs
|
||||
add_custom_command(OUTPUT ${docs_builder_output}
|
||||
COMMAND ${CMAKE_COMMAND}
|
||||
-E rename
|
||||
"latex/${CMAKE_PROJECT_NAME}.pdf"
|
||||
"${CMAKE_PROJECT_NAME}.pdf"
|
||||
APPEND
|
||||
VERBATIM)
|
||||
endif()
|
||||
|
||||
# OUTPUT is a fake target / symbolic name, not an actual file
|
||||
set_property(SOURCE ${docs_builder_output} PROPERTY SYMBOLIC 1)
|
||||
# Remove generated files when cleaning the build tree
|
||||
set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
|
||||
${builder}
|
||||
${docs_builder_log})
|
||||
|
||||
# Include this builder as a dependency of the general 'docs' target
|
||||
list(APPEND docs_outputs ${docs_builder_output})
|
||||
endforeach()
|
||||
|
||||
# Remove generated files when cleaning the build tree
|
||||
set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
|
||||
${CMAKE_PROJECT_NAME}HTML.tar.gz
|
||||
${CMAKE_PROJECT_NAME}.pdf)
|
||||
|
||||
add_custom_target(docs ALL DEPENDS ddsc_docs ${docs_outputs})
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
Binary file not shown.
|
Before Width: | Height: | Size: 27 KiB |
|
|
@ -1,178 +0,0 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# Note that not all possible configuration values are present in this
|
||||
# autogenerated file.
|
||||
#
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# If your documentation needs a minimal Sphinx version, state it here.
|
||||
#
|
||||
# needs_sphinx = '1.0'
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = ['sphinx.ext.autodoc',
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.coverage',
|
||||
'sphinx.ext.imgmath',
|
||||
'sphinx.ext.ifconfig',
|
||||
'breathe']
|
||||
|
||||
breathe_projects = { @sph_conf_breathe_projs@ }
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
#templates_path = ['@CMAKE_CURRENT_SOuRCE_DIR@/_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
# You can specify multiple suffix as a list of string:
|
||||
#
|
||||
# source_suffix = ['.rst', '.md']
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'@CMAKE_PROJECT_NAME_FULL@'
|
||||
copyright = u'@sph_conf_copyright@'
|
||||
author = u'@sph_conf_author@'
|
||||
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y.Z version.
|
||||
version = u'@sph_conf_version@'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = u'@sph_conf_release@'
|
||||
|
||||
# The language for content autogenerated by Sphinx. Refer to documentation
|
||||
# for a list of supported languages.
|
||||
#
|
||||
# This is also used if you do content translation via gettext catalogs.
|
||||
# Usually you set "language" from the command line for these cases.
|
||||
language = u'en'
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
exclude_patterns = []
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
# documentation.
|
||||
#
|
||||
# html_theme_options = {}
|
||||
|
||||
# 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 = ['@CMAKE_CURRENT_SOURCE_DIR@/_static']
|
||||
|
||||
# Custom sidebar templates, must be a dictionary that maps document names
|
||||
# to template names.
|
||||
#
|
||||
# This is required for the alabaster theme
|
||||
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
|
||||
html_sidebars = {
|
||||
'**': [
|
||||
'about.html',
|
||||
'navigation.html',
|
||||
'relations.html', # needs 'show_related': True theme option to display
|
||||
'searchbox.html',
|
||||
'donate.html',
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
# -- Options for HTMLHelp output ------------------------------------------
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = '@CMAKE_PROJECT_NAME_FULL@doc'
|
||||
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
'babel': '\\usepackage[english]{babel}'
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, '@CMAKE_PROJECT_NAME@.tex', u'@CMAKE_PROJECT_NAME_FULL@',
|
||||
u'@sph_conf_author@', 'manual'),
|
||||
]
|
||||
|
||||
latex_logo = u'@sph_logo@'
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
#man_pages = [
|
||||
# (master_doc, 'cyclonedds', u'Eclipse Cyclone DDS Documentation',
|
||||
# [author], 1)
|
||||
#]
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, '@CMAKE_PROJECT_NAME_FULL@', u'@CMAKE_PROJECT_NAME_FULL@ Documentation',
|
||||
author, '@CMAKE_PROJECT_NAME@', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
#intersphinx_mapping = {'https://docs.python.org/': None}
|
||||
|
|
@ -13,4 +13,4 @@ Eclipse Cyclone DDS C API Reference
|
|||
===================================
|
||||
|
||||
.. doxygenindex::
|
||||
:project: ddsc_api
|
||||
:project: ddsc_api_docs
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue