Fix #1378, 1589, doxygen cleanup #1612
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jphickey
added
the
CCB:Ready
skliper
reviewed
Jun 8, 2021
This was referenced Jun 9, 2021
Put the "detaildesign" and "users_guide" into separate working directories, and do a general cleanup/simplification of the generated doxyfiles. Detail design just includes all components, and use "exclude" where special treatment was needed, and to avoid UT code. Paths for each "arch" (target-specific) are written to separate files and included directly in the generated doxyfile, reducing the number of generated files/layers.
Use a unique file name for the doxygen warnings, instead of "warnings.log", so the mutiple documentation targets will not overwrite the other log file. Use a prefixed name so that if the log file is uploaded to the build artifacts, it will be identifiable. Detail Design warnings in: detaildesign-warnings.log Users Guide warnings in: cfe-usersguide-warnings.log
jphickey
force-pushed
the
fix-1378-1589-doxygen-cleanup
branch
from
24ddaf7
to
c67f217
Compare
|
In this incarnation, it can be merged and docs build as-is, but the detail design landing page (mainpage) shows up as the OSAL API guide, and a bunch of doxygen warnings will be shown about test code. When merged in conjunction with nasa/osal#1070, this is fixed again - landing page will be blank (or whatever the mission has provided) and the test/example code (and associated warnings) are also removed. |
skliper
approved these changes
Jun 9, 2021
|
CCB:2021-06-09 APPROVED
|
astrogeco
added
CCB:Approved
astrogeco
added a commit
to nasa/cFS
that referenced
this pull request
Jun 16, 2021
nasa/cFE#1600, Add workflow to build cFE documentation nasa/cFE#1609, Requirements updates nasa/cFE#1610, ES/ResourceID documentation cleanup nasa/cFE#1613, allow multiple sources in add_cfe_coverage_test nasa/cFE#1586, add ES Misc Functional test nasa/cFE#1607, add Mempool functional tests nasa/cFE#1605, Clean/simplify version header and reporting nasa/cFE#1612, 1589, doxygen cleanup nasa/cFE#1611, Prepend system log messages with function name
astrogeco
added a commit
to astrogeco/cFS
that referenced
this pull request
Jun 16, 2021
Update check in documentation build workflow to reflect new warnings logfile name for usersguide changed in nasa/cFE#1612
astrogeco
added a commit
to nasa/cFS
that referenced
this pull request
Jun 17, 2021
nasa/cFE#1619 - cfe v6.8.0-rc1+dev693 nasa/osal#1076 - osal v5.1.0-rc1+dev530 nasa/PSP#296 - psp v1.5.0-rc1+dev118 *Documentation Updates:* nasa/cFE#1598, Updated FS Read/WriteHeader API return documentation nasa/cFE#1601, Document CFE_ES_RunLoop increment task counter behavior nasa/cFE#1602, Document CFE_TBL_Unregister use-case nasa/cFE#1603, Update version description per current design *Standardize docs generation:* nasa/cFE#1615, standardize on "docs" subdirectory nasa/osal#1071, rename doc to docs nasa/PSP#294, rename doc to docs *Coding Standard:* nasa/osal#1042 nasa/PSP#292 **Mutex for UTAssert** nasa/cFE#1596, provide CFE assert lock/unlock nasa/osal#1065, add mutex lock around UtAssert globals *Resolve API-UT discrepancies:* nasa/osal#1055, idmap API nasa/osal#1056, file API nasa/osal#1057, filesys API nasa/osal#1060, socket API nasa/osal#1064, select API **Other cFE ixes** nasa/cFE#1566, Simplify CFE_FS_SetTimestamp and fix syslog typo nasa/cFE#1592, Removed redundant check/set of CFE_CPU_ID_VALUE nasa/cFE#1593, add time get reference error bit nasa/cFE#1600, Add workflow to build cFE documentation nasa/cFE#1609, Requirements updates nasa/cFE#1610, ES/ResourceID documentation cleanup nasa/cFE#1613, allow multiple sources in add_cfe_coverage_test nasa/cFE#1586, add ES Misc Functional test nasa/cFE#1607, add Mempool functional tests nasa/cFE#1605, Clean/simplify version header and reporting nasa/cFE#1612, doxygen cleanup nasa/cFE#1611, Prepend system log messages with function name nasa/osal#1063, const correct OS_SelectFdIsSet nasa/osal#1073, Fix OS_Select doxygen errors nasa/osal#1073, Add missing OS_Select param doc nasa/osal#1067, Add Workflow to build and verify OSAL API Guide nasa/osal#1070, add detail design template nasa/osal#1072, Update error codes and documentation nasa/osal#1075, Increase UT object limit for testing Co-authored-by: Jacob Hageman <skliper@users.noreply.github.com> Co-authored-by: Joseph Hickey <jphickey@users.noreply.github.com> Co-authored-by: Ariel Adams <ArielSAdamsNASA@users.noreply.github.com> Co-authored-by: Alex Campbell <zanzaben@users.noreply.github.com> Co-authored-by: Jose F Martinez Pedraza <pepepr08@users.noreply.github.com>
astrogeco
added a commit
to nasa/cFS
that referenced
this pull request
Jun 17, 2021
nasa/cFE#1619 - cfe v6.8.0-rc1+dev693 nasa/osal#1076 - osal v5.1.0-rc1+dev530 nasa/PSP#296 - psp v1.5.0-rc1+dev118 *Documentation Updates:* nasa/cFE#1598, Updated FS Read/WriteHeader API return documentation nasa/cFE#1601, Document CFE_ES_RunLoop increment task counter behavior nasa/cFE#1602, Document CFE_TBL_Unregister use-case nasa/cFE#1603, Update version description per current design *Standardize docs generation:* nasa/cFE#1615, standardize on "docs" subdirectory nasa/osal#1071, rename doc to docs nasa/PSP#294, rename doc to docs *Coding Standard:* nasa/osal#1042 nasa/PSP#292 **Mutex for UTAssert** nasa/cFE#1596, provide CFE assert lock/unlock nasa/osal#1065, add mutex lock around UtAssert globals *Resolve API-UT discrepancies:* nasa/osal#1055, idmap API nasa/osal#1056, file API nasa/osal#1057, filesys API nasa/osal#1060, socket API nasa/osal#1064, select API **Other cFE Fixes** nasa/cFE#1566, Simplify CFE_FS_SetTimestamp and fix syslog typo nasa/cFE#1592, Removed redundant check/set of CFE_CPU_ID_VALUE nasa/cFE#1593, add time get reference error bit nasa/cFE#1600, Add workflow to build cFE documentation nasa/cFE#1609, Requirements updates nasa/cFE#1610, ES/ResourceID documentation cleanup nasa/cFE#1613, allow multiple sources in add_cfe_coverage_test nasa/cFE#1586, add ES Misc Functional test nasa/cFE#1607, add Mempool functional tests nasa/cFE#1605, Clean/simplify version header and reporting nasa/cFE#1612, doxygen cleanup nasa/cFE#1611, Prepend system log messages with function name **Other osal Fixes** nasa/osal#1063, const correct OS_SelectFdIsSet nasa/osal#1073, Fix OS_Select doxygen errors nasa/osal#1073, Add missing OS_Select param doc nasa/osal#1067, Add Workflow to build and verify OSAL API Guide nasa/osal#1070, add detail design template nasa/osal#1072, Update error codes and documentation nasa/osal#1075, Increase UT object limit for testing Co-authored-by: Jacob Hageman <skliper@users.noreply.github.com> Co-authored-by: Joseph Hickey <jphickey@users.noreply.github.com> Co-authored-by: Ariel Adams <ArielSAdamsNASA@users.noreply.github.com> Co-authored-by: Alex Campbell <zanzaben@users.noreply.github.com> Co-authored-by: Jose F Martinez Pedraza <pepepr08@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Describe the contribution
Clean up and simplify the generated
Doxyfiles for the documentation builds. Instead of having special rules or providing direct refs to non-cFE subdirectories in the INPUT, just add the base dir for all modules. Then use "exclude" logic to filter out parts based on file/directory names (unit-test, ut-stubs, etc).Gives each cFE doc build (detaildesign, usersguide) its own dedicated working directory.
Fixes #1378
Fixes #1589
Testing performed
Build detail design and users guide docs and verify contents.
Built all 3 doc targets (detaildesign, usersguide, osalguide) numerous times with
-jmake option, did not see any issues related to parallelism.Expected behavior changes
The full set of code is included in the "detaildesign", even for OS/BSP/PSP layers that may not be used - e.g. RTEMS and VxWorks PSP and OSAL layers are included in this build.
After parallel builds and/or building all doc targets at once - the warning files for each doc target are left are intact, and can be reviewed individually after the build - they do not overwrite each other as they used to.
Note that instead of
warnings.logthe artifact is nowdetaildesign-warnings.logandcfe-usersguide-warnings.log, respectively.System(s) tested on
Ubuntu
Additional context
There had been some attempts at not including unused components in the past, but they were not working (pre-existing issue) so it was all getting included anyway, this simply takes out the broken logic but the end result is largely the same.
This may also require some sort of update to the list of artifacts due to the
warnings.logfile name change.Contributor Info - All information REQUIRED for consideration of pull request
Joseph Hickey, Vantage Systems, Inc.