docs: split ROMIO and HDF5 limits into distinct sections

adammoody commented 1 year ago

This updates our "limitations and workarounds" documentation to separate ROMIO and HDF5 into their own subsections. This also describes how to set ROMIO hints in more detail, and it clarifies some language about MPI_File_sync.

Good chance that I messed up the RST syntax along the way, since I haven't rendered the page to visualize the formatting.

Description

Motivation and Context

How Has This Been Tested?

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[ ] Performance enhancement (non-breaking change which improves efficiency)
[ ] Code cleanup (non-breaking change which makes code smaller or more readable)
[ ] Breaking change (fix or feature that would cause existing functionality to change)
[ ] Testing (addition of new tests or update to current tests)
[x] Documentation (a change to man pages or other documentation)

Checklist:

[ ] My code follows the UnifyFS code style requirements.
[ ] I have updated the documentation accordingly.
[ ] I have read the CONTRIBUTING document.
[ ] I have added tests to cover my changes.
[ ] All new and existing tests passed.
[ ] All commit messages are properly formatted.

adammoody commented 1 year ago

I noticed that the sync-barrier-sync barrier code block example here:

https://unifyfs.readthedocs.io/en/dev/limitations.html#manually-add-sync-operations

does not render when viewing the rst page in github:

https://github.com/LLNL/UnifyFS/blob/dev/docs/limitations.rst#manually-add-sync-operations

Based on this comment, apparently github has problems rendering code blocks with :caption: and just drops the entire block:

https://github.com/github/markup/issues/914#issuecomment-387823670

I verified that the code block comes back if :caption: is dropped.

adammoody commented 1 year ago

Thanks for your help on this one, @CamStan and @MichaelBrim . I decided to merge once I figured out that the dropped code block was specific to github, so it should show up on readthedocs. If things look ugly on readthedocs, I can submit follow up fixes.

CamStan commented 1 year ago

...apparently github has problems rendering code blocks with :caption: and just drops the entire block

Good to know! Thank you @adammoody

LLNL / UnifyFS