Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Omnitrace docs refactoring #353

Merged
merged 67 commits into from
Jul 29, 2024

Conversation

amd-jnovotny
Copy link
Contributor

This PR contains the changes necessary to integrate Omnitrace into the ROCm documentation environment for release 6.2. It involves the following tasks:

  • Moving the documentation out of source/docs and into the main docs directory.
  • Moving some existing pages into subdirectories to conform to the ROCm categories of tutorials, how to, conceptual background, and reference materials. Some existing pages might be split up into multiple pages in the new arrangement, while other pages might combine material from two existing pages.
  • Reformatting the material from Markdown to rst.
  • Changing a few page and section titles for greater consistency with other ROCm documentation hubs.
  • Making some behind-the-scenes changes to accommodate our Read the Docs publishing pipeline and conform to the ROCm documentation standard look-and-feel.

Commits will be done in stages. The initial commit includes the main index file and a slightly rewritten "What is Omnitrace?" page, along with some scaffolding changes. New pages will be pushed regularly as work proceeds.

@peterjunpark peterjunpark added the documentation Improvements or additions to documentation label Jun 21, 2024
@samjwu
Copy link
Member

samjwu commented Jun 21, 2024

closing and reopening to trigger RTD pr builds

@samjwu samjwu closed this Jun 21, 2024
@samjwu samjwu reopened this Jun 21, 2024
@samjwu
Copy link
Member

samjwu commented Jun 28, 2024

todo: generate Doxyfile from the cmake

@jrmadsen jrmadsen changed the title Omnitrace refactoring Omnitrace docs refactoring Jul 2, 2024
@amd-jnovotny
Copy link
Contributor Author

The content is basically ready for review with a few caveats:
-- The API structure and links need to be finalized. Omnitrace uses a different structure than rocDecode and others, which provide additional formatting.
-- We need to decide on a redirect strategy for the existing content
-- The old docs files remain in source/docs in case anyone wants to cross-reference them. They will eventually be removed.
-- I intend to do a final sweep through the docs for formatting and typos.

@amd-jnovotny amd-jnovotny marked this pull request as ready for review July 2, 2024 20:01
@amd-jnovotny amd-jnovotny requested a review from a team as a code owner July 2, 2024 20:01
README.md Outdated Show resolved Hide resolved
docs/.gitignore Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
docs/conceptual/omnitrace-feature-set.rst Outdated Show resolved Hide resolved
docs/conceptual/omnitrace-feature-set.rst Outdated Show resolved Hide resolved
docs/conceptual/omnitrace-feature-set.rst Show resolved Hide resolved
docs/conceptual/omnitrace-feature-set.rst Outdated Show resolved Hide resolved
docs/conceptual/how-omnitrace-works.rst Outdated Show resolved Hide resolved
docs/conceptual/how-omnitrace-works.rst Outdated Show resolved Hide resolved
docs/conceptual/how-omnitrace-works.rst Outdated Show resolved Hide resolved
docs/doxygen/Doxyfile Outdated Show resolved Hide resolved
docs/what-is-omnitrace.rst Outdated Show resolved Hide resolved
docs/install/quick-start.rst Outdated Show resolved Hide resolved
docs/conceptual/omnitrace-feature-set.rst Show resolved Hide resolved
docs/install/quick-start.rst Show resolved Hide resolved
docs/install/install.rst Outdated Show resolved Hide resolved
docs/install/install.rst Outdated Show resolved Hide resolved
docs/install/install.rst Outdated Show resolved Hide resolved
docs/install/install.rst Outdated Show resolved Hide resolved
docs/install/install.rst Outdated Show resolved Hide resolved
docs/how-to/using-omnitrace-api.rst Outdated Show resolved Hide resolved
docs/how-to/using-omnitrace-api.rst Show resolved Hide resolved
docs/conceptual/omnitrace-feature-set.rst Outdated Show resolved Hide resolved
docs/how-to/using-omnitrace-api.rst Outdated Show resolved Hide resolved
Copy link
Collaborator

@dgaliffiAMD dgaliffiAMD left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still working through reviewing all of the "How-Tos". Here is the latest batch.

docs/how-to/configuring-runtime-options.rst Outdated Show resolved Hide resolved
docs/how-to/configuring-runtime-options.rst Outdated Show resolved Hide resolved
docs/how-to/configuring-runtime-options.rst Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/sampling-call-stack.rst Outdated Show resolved Hide resolved
docs/how-to/instrumenting-rewriting-binary-application.rst Outdated Show resolved Hide resolved
docs/how-to/performing-causal-profiling.rst Outdated Show resolved Hide resolved
docs/how-to/performing-causal-profiling.rst Outdated Show resolved Hide resolved
docs/how-to/performing-causal-profiling.rst Outdated Show resolved Hide resolved
docs/how-to/performing-causal-profiling.rst Outdated Show resolved Hide resolved
docs/how-to/performing-causal-profiling.rst Outdated Show resolved Hide resolved
docs/reference/development-guide.rst Outdated Show resolved Hide resolved
docs/reference/development-guide.rst Outdated Show resolved Hide resolved
docs/how-to/troubleshooting-omnitrace-linux.rst Outdated Show resolved Hide resolved
docs/reference/development-guide.rst Outdated Show resolved Hide resolved
amd-jnovotny and others added 21 commits July 29, 2024 15:19
* Add CMake CACHE Variable ElfUtils_DOWNLOAD_URL

Used to override the default URL to download ElfUtils from.
Useful for internal builds

Also, include a mirror to fallback to if the override URL fails.

* Update timemory submodule

Updating to include the BINUTIL_DOWNLOAD_URL override cmake
variable.

---------

Signed-off-by: David Galiffi <David.Galiffi@amd.com>
Document location is being refactored.
@samjwu samjwu dismissed stale reviews from dgaliffiAMD and themself via a54c3f9 July 29, 2024 21:20
@samjwu samjwu force-pushed the omnitrace-refactor-main branch from 1c7bd30 to a54c3f9 Compare July 29, 2024 21:20
@amd-jnovotny amd-jnovotny merged commit 0689797 into ROCm:main Jul 29, 2024
61 of 101 checks passed
samjwu added a commit to samjwu/omnitrace that referenced this pull request Jul 29, 2024
* Add Sphinx and Read the Docs configs

* Add documentation workflow configurations

* Changed macros verbprintf and verbprintf_bare so they write to stdout… (ROCm#346)

Flush stdout when listing keys + bump verbose level for GPU count

* Removing static version asserts. (ROCm#347)

It is causing failures on our internal builds

Signed-off-by: David Galiffi <David.Galiffi@amd.com>

* Check for an empty vector before popping (ROCm#350)

Protect from possible seg. fault

Signed-off-by: David Galiffi <David.Galiffi@amd.com>

* Add release links to installation.md (ROCm#351)

* Initial infrastructure rework for Omnitrace refactoring and a rewrite of the What is file

* Add files in conceptual section, along with images and infrastructure changes.

* Formatting and style fixes for files in conceptual directory

* Add quick start install guide and fix spelling errors in other files

* Add install document and fix code tags. Infrastructure changes

* Add two how-to guides along with infra changes and spelling fixes

* Add two new how to files and fix errors in the last commit

* Fix spelling mistakes

* Add new how to file on causal profiling and infra changes.

* Add how to file on interpreting Omnitrace output, fixes, and images

* Add remaining how-to guides and reference materials along with fixes and infrastructure

* Add YouTube file and fix spelling and formatting

* Fix a few loose ends and add link to license page

* Add Sphinx and Doxygen infrastructure and some additional corrections

* Update rocm-docs-core

* Fix Doxyfile

* Fix path to API header files

* Run doxysphinx in conf.py

* Add back custom css for doxygen

* Remove doxygenlayout

* Add api to toc

* Update Doxyfile

Generate from source .in

* Proofreading edits and other changes

* Add .gitignore for Doxygen and remove deprecated words and typos

* Fix one additional typo

* Turn off dot

* Update doxyfile strip from path

* Workflow, submodules, and thread info Updates (ROCm#352)

* Update CI workflows

- use node20 workflow packages

* Update tests/source/CMakeLists.txt

- Use OMNITRACE_TRACE and OMNTRACE_PROFILE instead of perfetto/timemory

* Update timemory submodule

- argparse: requires -> required
- parse callbacks

* Update thread_info.cpp

- fix causal::delay::get_local usage

* Update timemory submodule

* Update kokkos submodule

- release 3.7.02

* Revert opensuse.yml and ubuntu-bionic.yml to use node16 workflows

* Update docs.yml

* ROCm 6.1 Installers (ROCm#349)

* Add ROCm 6.1 to packages
* Bump version to 1.11.3
* Add 6.1 support to the docker build support.
   Simplified this by adding 6.* to case statements, now that repo links have been standardized.

* Update timemory submodule (ROCm#354)

- fix argparse::argument::required template deduction

* Build omnitrace-rt library (ROCm#355)

* Build omnitrace-rt library

- Explicitly build dyninstAPI_RT as omnitrace-rt so that the SONAME in the ELF is omnitrace-rt instead of dyninstAPI_RT
- Create symbolic link lib/omnitrace/libdyninstAPI_RT.so which points to lib/libomnitrace-rt.so
- Simplify build tree location of libomnitrace-rt.so since it is ../lib from the bin directory even in the build tree
- Update dyninst submodule with minor tweaks to dyninstAPI_RT/CMakeLists.txt

* Update source/lib/omnitrace-rt/cmake/platform.cmake

* Use ftpmirror.gnu.org instead of ftp.gnu.org

- in timemory and dyninst submodules
- minor .clang-tidy tweak

* Executables append omnitrace library directory to LD_LIBRARY_PATH (ROCm#356)

- omnitrace-run, omnitrace-sample, and omnitrace-causal now automatically append the LD_LIBRARY_PATH with the directory containing the omnitrace libraries
  - this helps ensure that binary rewritten exes can resolve omnitrace-rt library location

* Fix a few typos and formatting issues

* Additional fixes and minor formatting changes.

* More fixes and minor formatting changes.

* Complete second proofreading with fixes and minor formatting changes.

* Make changes to table of contents and disable linting

* Update links in the README doc to reflect the new structure.

* Align intro on the Omnitrace index page with the first paragraph of the what-is page

* Changes and edits based on review comments

* Additional changes and edits based on external review

* Additional updates and changes from the external review of Omnitrace

* Additional changes based on the external review

* New round of edits based on the external review

* Additional edits based on the external review

* Changes to address comments from the internal review

* Correct to the RHEL SELinux note in the troubleshooting guide

* One additional change to the development guide code example

* Move troubleshooting to post-install of install.rst and other minor edits.

* Remove troubleshooting page and modify new post-install troubleshooting section on install.rst

* Refactor the how Omnitrace works page into seperate topics and redo infrastructure

* API ToC changes

* Additional API and ToC changes

* Back out API and ToC changes and update requirements.txt

* Additional API and ToC changes

* Add commit for signing purposes

* Add ElfUtils and BinUtils Download URL Overrides (ROCm#358)

* Add CMake CACHE Variable ElfUtils_DOWNLOAD_URL

Used to override the default URL to download ElfUtils from.
Useful for internal builds

Also, include a mirror to fallback to if the override URL fails.

* Update timemory submodule

Updating to include the BINUTIL_DOWNLOAD_URL override cmake
variable.

---------

Signed-off-by: David Galiffi <David.Galiffi@amd.com>

* Remove Ubuntu 18.04 and SUSE 15.2

* Update checkout action to v4

* Add `docs/**` to `paths-ignore`

Document location is being refactored.

* Modified submodules dyninst and timemory. (ROCm#361)

---------

Signed-off-by: David Galiffi <David.Galiffi@amd.com>
Co-authored-by: Peter Jun Park <peter.park@amd.com>
Co-authored-by: ajanicijamd <Aleksandar.Janicijevic@amd.com>
Co-authored-by: David Galiffi <David.Galiffi@amd.com>
Co-authored-by: Jonathan R. Madsen <jrmadsen@users.noreply.github.com>
Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com>
samjwu added a commit that referenced this pull request Jul 31, 2024
Omnitrace docs refactoring (#353)

---------

Signed-off-by: David Galiffi <David.Galiffi@amd.com>
Co-authored-by: Jeffrey Novotny <jnovotny@amd.com>
Co-authored-by: Peter Jun Park <peter.park@amd.com>
Co-authored-by: ajanicijamd <Aleksandar.Janicijevic@amd.com>
Co-authored-by: David Galiffi <David.Galiffi@amd.com>
Co-authored-by: Jonathan R. Madsen <jrmadsen@users.noreply.github.com>
@amd-jnovotny amd-jnovotny deleted the omnitrace-refactor-main branch September 23, 2024 17:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants