forked from OSchip/llvm-project
[flang][docs] Doxygen support in flang.
Summary:
Added support for doxygen-style documentation generation from source code.
Added -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON flags to cmake.
Added the target doxygen-flang for building doxygen
Updated README.txt
Reviewers: DavidTruby, richard.barton.arm, sscalpone, mehdi_amini, jdoerfert
Reviewed By: DavidTruby, richard.barton.arm, sscalpone
Previous review: https://github.com/flang-compiler/f18/pull/1065
Differential Revision: https://reviews.llvm.org/D78136
This commit is contained in:
sameeran joshi
Sameeran joshi
parent
811c0c9eb4
commit
807fe05d35
|
|
@ -122,6 +122,10 @@ project(Flang)
|
|||
"Generate build targets for the Flang unit tests."
|
||||
ON)
|
||||
add_custom_target(check-all DEPENDS check-flang)
|
||||
if (LLVM_BUILD_DOCS)
|
||||
add_custom_target(doxygen ALL)
|
||||
endif()
|
||||
|
||||
else()
|
||||
option(FLANG_INCLUDE_TESTS
|
||||
"Generate build targets for the Flang unit tests."
|
||||
|
|
@ -332,12 +336,11 @@ if (FLANG_INCLUDE_TESTS)
|
|||
add_subdirectory(unittests)
|
||||
endif()
|
||||
|
||||
# TODO: Add doxygen support.
|
||||
#option(FLANG_INCLUDE_DOCS "Generate build targets for the Flang docs."
|
||||
# ${LLVM_INCLUDE_DOCS})
|
||||
#if (FLANG_INCLUDE_DOCS)
|
||||
# add_subdirectory(documentation)
|
||||
#endif()
|
||||
option(FLANG_INCLUDE_DOCS "Generate build targets for the Flang docs."
|
||||
${LLVM_INCLUDE_DOCS})
|
||||
if (FLANG_INCLUDE_DOCS)
|
||||
add_subdirectory(docs)
|
||||
endif()
|
||||
|
||||
# Custom target to install Flang libraries.
|
||||
add_custom_target(flang-libraries)
|
||||
|
|
|
|||
|
|
@ -159,8 +159,24 @@ flang_site_config and flang_config. And they can be set as shown bellow:
|
|||
<path-to-fortran-test>
|
||||
```
|
||||
|
||||
# How to Generate FIR Documentation
|
||||
# How to Generate Documentation
|
||||
|
||||
If f18 was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
|
||||
## Generate FIR Documentation
|
||||
If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
|
||||
generate FIR language documentation by running `make flang-doc`. This will
|
||||
create `docs/Dialect/FIRLangRef.md` in f18 build directory.
|
||||
create `docs/Dialect/FIRLangRef.md` in flang build directory.
|
||||
|
||||
## Generate Doxygen-based Documentation
|
||||
To generate doxygen-style documentation from source code
|
||||
- Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
|
||||
|
||||
```
|
||||
cd ~/llvm-project/build
|
||||
cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
|
||||
make doxygen-flang
|
||||
|
||||
It will generate html in
|
||||
|
||||
<build-dir>/tools/flang/docs/doxygen/html # for flang docs
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,105 @@
|
|||
|
||||
find_package(Doxygen)
|
||||
if (DOXYGEN_FOUND)
|
||||
if (LLVM_ENABLE_DOXYGEN)
|
||||
set(abs_top_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
|
||||
set(abs_top_builddir ${CMAKE_CURRENT_BINARY_DIR})
|
||||
|
||||
if (HAVE_DOT)
|
||||
set(DOT ${LLVM_PATH_DOT})
|
||||
endif()
|
||||
|
||||
if (LLVM_DOXYGEN_EXTERNAL_SEARCH)
|
||||
set(enable_searchengine "YES")
|
||||
set(searchengine_url "${LLVM_DOXYGEN_SEARCHENGINE_URL}")
|
||||
set(enable_server_based_search "YES")
|
||||
set(enable_external_search "YES")
|
||||
set(extra_search_mappings "${LLVM_DOXYGEN_SEARCH_MAPPINGS}")
|
||||
else()
|
||||
set(enable_searchengine "NO")
|
||||
set(searchengine_url "")
|
||||
set(enable_server_based_search "NO")
|
||||
set(enable_external_search "NO")
|
||||
set(extra_search_mappings "")
|
||||
endif()
|
||||
|
||||
# If asked, configure doxygen for the creation of a Qt Compressed Help file.
|
||||
if (LLVM_ENABLE_DOXYGEN_QT_HELP)
|
||||
set(FLANG_DOXYGEN_QCH_FILENAME "org.llvm.flang.qch" CACHE STRING
|
||||
"Filename of the Qt Compressed help file")
|
||||
set(FLANG_DOXYGEN_QHP_NAMESPACE "org.llvm.flang" CACHE STRING
|
||||
"Namespace under which the intermediate Qt Help Project file lives")
|
||||
set(FLANG_DOXYGEN_QHP_CUST_FILTER_NAME "FLANG ${FLANG_VERSION}" CACHE STRING
|
||||
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
|
||||
set(FLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS "FLANG,${FLANG_VERSION}" CACHE STRING
|
||||
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
|
||||
set(flang_doxygen_generate_qhp "YES")
|
||||
set(flang_doxygen_qch_filename "${FLANG_DOXYGEN_QCH_FILENAME}")
|
||||
set(flang_doxygen_qhp_namespace "${FLANG_DOXYGEN_QHP_NAMESPACE}")
|
||||
set(flang_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
|
||||
set(flang_doxygen_qhp_cust_filter_name "${FLANG_DOXYGEN_QHP_CUST_FILTER_NAME}")
|
||||
set(flang_doxygen_qhp_cust_filter_attrs "${FLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
|
||||
else()
|
||||
set(flang_doxygen_generate_qhp "NO")
|
||||
set(flang_doxygen_qch_filename "")
|
||||
set(flang_doxygen_qhp_namespace "")
|
||||
set(flang_doxygen_qhelpgenerator_path "")
|
||||
set(flang_doxygen_qhp_cust_filter_name "")
|
||||
set(flang_doxygen_qhp_cust_filter_attrs "")
|
||||
endif()
|
||||
|
||||
option(LLVM_DOXYGEN_SVG
|
||||
"Use svg instead of png files for doxygen graphs." OFF)
|
||||
if (LLVM_DOXYGEN_SVG)
|
||||
set(DOT_IMAGE_FORMAT "svg")
|
||||
else()
|
||||
set(DOT_IMAGE_FORMAT "png")
|
||||
endif()
|
||||
|
||||
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
|
||||
${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
|
||||
|
||||
set(abs_top_srcdir)
|
||||
set(abs_top_builddir)
|
||||
set(DOT)
|
||||
set(enable_searchengine)
|
||||
set(searchengine_url)
|
||||
set(enable_server_based_search)
|
||||
set(enable_external_search)
|
||||
set(extra_search_mappings)
|
||||
set(flang_doxygen_generate_qhp)
|
||||
set(flang_doxygen_qch_filename)
|
||||
set(flang_doxygen_qhp_namespace)
|
||||
set(flang_doxygen_qhelpgenerator_path)
|
||||
set(flang_doxygen_qhp_cust_filter_name)
|
||||
set(flang_doxygen_qhp_cust_filter_attrs)
|
||||
set(DOT_IMAGE_FORMAT)
|
||||
|
||||
add_custom_target(doxygen-flang
|
||||
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating flang doxygen documentation." VERBATIM)
|
||||
|
||||
if (LLVM_BUILD_DOCS)
|
||||
add_dependencies(doxygen doxygen-flang)
|
||||
endif()
|
||||
|
||||
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY AND LLVM_BUILD_DOCS)
|
||||
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
|
||||
DESTINATION docs/html)
|
||||
endif()
|
||||
endif()
|
||||
endif()
|
||||
|
||||
if (LLVM_ENABLE_SPHINX)
|
||||
include(AddSphinxTarget)
|
||||
if (SPHINX_FOUND)
|
||||
if (${SPHINX_OUTPUT_HTML})
|
||||
add_sphinx_target(html flang)
|
||||
endif()
|
||||
if (${SPHINX_OUTPUT_MAN})
|
||||
add_sphinx_target(man flang)
|
||||
endif()
|
||||
endif()
|
||||
endif()
|
||||
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
/// \mainpage flang
|
||||
///
|
||||
/// \section main_intro Introduction
|
||||
/// Welcome to the flang project.
|
||||
///
|
||||
/// This documentation describes the **internal** software that makes
|
||||
/// up flang, not the **external** use of flang. There are no instructions
|
||||
/// here on how to use flang, only the APIs that make up the software. For
|
||||
/// usage instructions, please see the [project website](https://github.com/flang-compiler/f18)
|
||||
/// for further detail.
|
||||
///
|
||||
/// \section main_caveat Caveat
|
||||
/// This documentation is generated directly from the source code with doxygen.
|
||||
/// Since flang is constantly under active development, what you're about to
|
||||
/// read is out of date!
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue