Fix release docs workflow + update documentation (#216)
* Fix release-docs workflow
* Documentation updates
- warning as errors when building docs
- fixed warnings when building docs
- fixed doxygen comments
* Miscellaneous fixes
* Fix doxygen comments
[ROCm/rocprofiler-systems commit: 7ecc037d17]
Cette révision appartient à :
Jonathan R. Madsen
révisé par
GitHub
GitHub
Parent
35f639a2b5
révision
75e1e8bf37
@@ -131,10 +131,12 @@ breathe_projects = {"omnitrace": "_doxygen/xml"}
|
||||
breathe_default_project = "omnitrace"
|
||||
breathe_default_members = ("members",)
|
||||
breathe_projects_source = {
|
||||
"auto": (
|
||||
os.path.join(project_root, "source"),
|
||||
"omnitrace": (
|
||||
os.path.join(project_root, "source", "lib", "omnitrace-user"),
|
||||
[
|
||||
"lib/omnitrace-user/omnitrace/user.h",
|
||||
"omnitrace/types.h",
|
||||
"omnitrace/categories.h",
|
||||
"omnitrace/user.h",
|
||||
],
|
||||
)
|
||||
}
|
||||
|
||||
@@ -40,6 +40,8 @@ EXTENSION_MAPPING = hpp=C++ \
|
||||
cpp=C++ \
|
||||
hh=C++ \
|
||||
cc=C++ \
|
||||
h=C \
|
||||
c=C \
|
||||
py=Python
|
||||
MARKDOWN_SUPPORT = YES
|
||||
TOC_INCLUDE_HEADINGS = 2
|
||||
@@ -105,14 +107,16 @@ WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = YES
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_NO_PARAMDOC = YES
|
||||
WARN_AS_ERROR = NO
|
||||
WARN_AS_ERROR = YES
|
||||
WARN_FORMAT = "---> WARNING! $file:$line: $text"
|
||||
WARN_LOGFILE = doc/warnings.log
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the input files
|
||||
#---------------------------------------------------------------------------
|
||||
INPUT = @SOURCE_DIR@/README.md \
|
||||
@SOURCE_DIR@/source/lib/omnitrace-user
|
||||
@SOURCE_DIR@/source/lib/omnitrace-user/omnitrace/types.h \
|
||||
@SOURCE_DIR@/source/lib/omnitrace-user/omnitrace/categories.h \
|
||||
@SOURCE_DIR@/source/lib/omnitrace-user/omnitrace/user.h
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS = *.h \
|
||||
*.hh \
|
||||
@@ -212,7 +216,7 @@ QHP_CUST_FILTER_ATTRS =
|
||||
QHP_SECT_FILTER_ATTRS =
|
||||
QHG_LOCATION =
|
||||
GENERATE_ECLIPSEHELP = NO
|
||||
ECLIPSE_DOC_ID = org.doxygen.timemory
|
||||
ECLIPSE_DOC_ID = org.doxygen.omnitrace
|
||||
DISABLE_INDEX = NO
|
||||
GENERATE_TREEVIEW = YES
|
||||
ENUM_VALUES_PER_LINE = 1
|
||||
@@ -306,9 +310,8 @@ ENABLE_PREPROCESSING = YES
|
||||
MACRO_EXPANSION = YES
|
||||
EXPAND_ONLY_PREDEF = NO
|
||||
SEARCH_INCLUDES = YES
|
||||
INCLUDE_PATH = @SOURCE_DIR@/source/timemory
|
||||
INCLUDE_PATH = @SOURCE_DIR@/source/lib/omnitrace-user
|
||||
INCLUDE_FILE_PATTERNS = *.h \
|
||||
*.hh \
|
||||
*.hpp
|
||||
PREDEFINED = OMNITRACE_PUBLIC_API= \
|
||||
OMNITRACE_HIDDEN_API= \
|
||||
@@ -316,6 +319,8 @@ PREDEFINED = OMNITRACE_PUBLIC_API= \
|
||||
"OMNITRACE_VISIBILITY(...)=" \
|
||||
"__attribute__(x)=" \
|
||||
"__declspec(x)=" \
|
||||
"size_t=unsigned long" \
|
||||
"uintptr_t=unsigned long" \
|
||||
DOXYGEN_SHOULD_SKIP_THIS
|
||||
EXPAND_AS_DEFINED =
|
||||
SKIP_FUNCTION_MACROS = NO
|
||||
|
||||
@@ -19,9 +19,10 @@ cmake -DSOURCE_DIR=${SOURCE_DIR} -P ${WORK_DIR}/generate-doxyfile.cmake
|
||||
|
||||
message "Generating doxygen xml files"
|
||||
doxygen omnitrace.dox
|
||||
doxygen omnitrace.dox
|
||||
|
||||
message "Building html documentation"
|
||||
make html
|
||||
make html SPHINXOPTS="-W --keep-going -n"
|
||||
|
||||
if [ -d ${SOURCE_DIR}/docs ]; then
|
||||
message "Removing stale documentation in ${SOURCE_DIR}/docs/"
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# User API
|
||||
|
||||
```eval_rst
|
||||
.. doxygenfile:: omnitrace/types.h
|
||||
.. doxygenfile:: omnitrace/categories.h
|
||||
.. doxygenfile:: omnitrace/user.h
|
||||
```
|
||||
|
||||
@@ -14,12 +16,16 @@ recorded, regardless of whether whether `omnitrace_user_start_*` or `omnitrace_u
|
||||
### User API Implementation
|
||||
|
||||
```cpp
|
||||
#include <omnitrace/categories.h>
|
||||
#include <omnitrace/types.h>
|
||||
#include <omnitrace/user.h>
|
||||
|
||||
#include <atomic>
|
||||
#include <cassert>
|
||||
#include <cerrno>
|
||||
#include <cstdio>
|
||||
#include <cstdlib>
|
||||
#include <cstring>
|
||||
#include <sstream>
|
||||
#include <thread>
|
||||
#include <vector>
|
||||
@@ -37,19 +43,16 @@ custom_push_region(const char* name);
|
||||
|
||||
namespace
|
||||
{
|
||||
int (*omnitrace_push_region_f)(const char*) = nullptr;
|
||||
}
|
||||
omnitrace_user_callbacks_t custom_callbacks = OMNITRACE_USER_CALLBACKS_INIT;
|
||||
omnitrace_user_callbacks_t original_callbacks = OMNITRACE_USER_CALLBACKS_INIT;
|
||||
} // namespace
|
||||
|
||||
int
|
||||
main(int argc, char** argv)
|
||||
{
|
||||
// get the internal callback to start a user-defined region
|
||||
omnitrace_user_get_callbacks(OMNITRACE_USER_REGION, (void**) &omnitrace_push_region_f,
|
||||
nullptr);
|
||||
// assign the custom callback to start a user-defined region
|
||||
if(omnitrace_push_region_f)
|
||||
omnitrace_user_configure(OMNITRACE_USER_REGION, (void*) &custom_push_region,
|
||||
nullptr);
|
||||
custom_callbacks.push_region = &custom_push_region;
|
||||
omnitrace_user_configure(OMNITRACE_USER_UNION_CONFIG, custom_callbacks,
|
||||
&original_callbacks);
|
||||
|
||||
omnitrace_user_push_region(argv[0]);
|
||||
omnitrace_user_push_region("initialization");
|
||||
@@ -71,9 +74,7 @@ main(int argc, char** argv)
|
||||
omnitrace_user_stop_thread_trace();
|
||||
for(size_t i = 0; i < nthread; ++i)
|
||||
{
|
||||
size_t _nitr = ((i % 2) == 1) ? (nitr - (0.1 * nitr)) : (nitr + (0.1 * nitr));
|
||||
long _nfib = ((i % 2) == 1) ? (nfib - (0.1 * nfib)) : (nfib + (0.1 * nfib));
|
||||
threads.emplace_back(&run, _nitr, _nfib);
|
||||
threads.emplace_back(&run, nitr, nfib);
|
||||
}
|
||||
// re-enable instrumentation
|
||||
omnitrace_user_start_thread_trace();
|
||||
@@ -117,8 +118,28 @@ run(size_t nitr, long n)
|
||||
int
|
||||
custom_push_region(const char* name)
|
||||
{
|
||||
if(!original_callbacks.push_region || !original_callbacks.push_annotated_region)
|
||||
return OMNITRACE_USER_ERROR_NO_BINDING;
|
||||
|
||||
printf("Pushing custom region :: %s\n", name);
|
||||
return (*omnitrace_push_region_f)(name);
|
||||
|
||||
if(original_callbacks.push_annotated_region)
|
||||
{
|
||||
int32_t _err = errno;
|
||||
char* _msg = nullptr;
|
||||
char _buff[1024];
|
||||
if(_err != 0) _msg = strerror_r(_err, _buff, sizeof(_buff));
|
||||
|
||||
omnitrace_annotation_t _annotations[] = {
|
||||
{ "errno", OMNITRACE_INT32, &_err }, { "strerror", OMNITRACE_STRING, _msg }
|
||||
};
|
||||
|
||||
errno = 0; // reset errno
|
||||
return (*original_callbacks.push_annotated_region)(
|
||||
name, _annotations, sizeof(_annotations) / sizeof(omnitrace_annotation_t));
|
||||
}
|
||||
|
||||
return (*original_callbacks.push_region)(name);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Référencer dans un nouveau ticket
Bloquer un utilisateur