readthedocs updates (#877)

* readthedocs updates

* Adding License

* correcting table of contents path

* Move doc requirements to sphinx dir

* Compile requirements.txt

* Update path to reqs

* Adding missing python module

* changing sphinx version

* changing docutils version

* enabling sphinx extensions

* trying sphinx-rtd-theme

* Remove unused doc configs

* Remove unused html theme options

* Add files to toc

* temp commit to test

* updating environment.yml for CI build

* Update doc requirements

To include rocprofiler-sdk in projects.yaml

* Set external_projects_current_project as rocprofiler-sdk

* Exclude external projects

* Fix warning for missing static path

* updating conf.py

* Removing reST syntax

* Use rocm-docs-core doxygen integration

* Remove RST syntax from Markdown files

* Generate doxyfile post checkout on RTD

* Use custom RTD env

* Specify mambaforge

* Put conda before post checkout cmd

* Add doxyfile for RTD

* Run cmake from conf.py

* Update environment.yml

* Use mambaforge

* Fix path to environment.yml

* Call build doxyfile

* Add Developer API title to Doxyfile

* Config version header

* Fix typo in conf.py

* Format fix for conf.py

* Increasing timeout for build-docs-from-source

* Remove README as mainpage for doxyfile

* Fix formatting in conf.py

---------

Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com>

.github/workflows/docs.yml

@@ -101,7 +101,7 @@ jobs:
           python3 -m pip install -r requirements.txt
 
       - name: Configure, Build, Install, and Package
-        timeout-minutes: 30
+        timeout-minutes: 60
         shell: bash
         run:
           export CMAKE_PREFIX_PATH=/opt/rocm:${CMAKE_PREFIX_PATH};

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+  configuration: source/docs/conf.py
+
+formats: [htmlzip, pdf, epub]
+
+python:
+  install:
+  - requirements: source/docs/sphinx/requirements.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-22.9"
+
+conda:
+   environment: source/docs/environment.yml

source/docs/.gitignore

@@ -3,3 +3,5 @@
 /_doxygen
 /.gitinfo
 /*.dox
+/.sass-cache
+/_toc.yml

source/docs/CMakeLists.txt

@@ -94,7 +94,7 @@ conda activate rocprofiler-docs
 
 which python
 
-python -m pip install -r ${CMAKE_CURRENT_LIST_DIR}/requirements.txt
+python -m pip install -r ${CMAKE_CURRENT_LIST_DIR}/sphinx/requirements.txt
 
 WORK_DIR=${PROJECT_SOURCE_DIR}/source/docs
 SOURCE_DIR=${PROJECT_SOURCE_DIR}

source/docs/_toc.yml.in

@@ -0,0 +1,23 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+defaults:
+  numbered: True
+  maxdepth: 4
+
+root: index
+subtrees:
+  - caption: Table of Contents
+    entries: 
+    - file: features
+    - file: installation
+    - file: tool_library_overview
+    - file: callback_services
+    - file: buffered_services
+    - file: pc_sampling
+    - file: intercept_table
+    - file: _doxygen/html/index
+    - file: samples
+    - file: rocprofv3
+  - caption: License
+    entries:
+    - file: license

source/docs/buffered_services.md

@@ -4,12 +4,6 @@ For the buffered approach, supported buffer record categories are enumerated in
 
 ## Buffered Tracing Services
 
-```eval_rst
-.. toctree::
-   :glob:
-   :maxdepth: 4
-```
-
 ## Overview
 
 In buffered approach, callbacks are receieved for batches of records from an internal (background) thread. Supported buffered tracing services are enumerated in  `rocprofiler_buffer_tracing_kind_t`.

source/docs/callback_services.md

@@ -1,11 +1,5 @@
 # Callback Tracing Services
 
-```eval_rst
-.. toctree::
-   :glob:
-   :maxdepth: 4
-```
-
 ## Overview
 
 ## Code Object Tracing

source/docs/conf.py

@@ -9,9 +9,6 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# sys.path.insert(0, os.path.abspath('.'))
 
 import os
 import sys
@@ -30,134 +27,81 @@ def install(package):
 # Check if we're running on Read the Docs' servers
 read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
 
+_srcdir = os.path.realpath(os.path.join(os.getcwd(), "../.."))
+
+
+def build_doxyfile():
+    sp.run(
+        [
+            "cmake",
+            f"-DSOURCE_DIR={_srcdir}",
+            "-DPROJECT_NAME='Rocprofiler SDK'",
+            f"-P {_srcdir}/source/docs/generate-doxyfile.cmake",
+        ]
+    )
+
+
+def configure_version_header():
+    sp.run(
+        [
+            "cmake",
+            f"-S {_srcdir}/source/include/rocprofiler-sdk",
+            f"-B {_srcdir}/source/include/rocprofiler-sdk",
+        ]
+    )
+
+
+configure_version_header()
+build_doxyfile()
 
 # -- Project information -----------------------------------------------------
 project = "Rocprofiler SDK"
-copyright = "2023, Advanced Micro Devices, Inc."
+copyright = "2023-2024, Advanced Micro Devices, Inc."
 author = "Advanced Micro Devices, Inc."
 
 project_root = os.path.normpath(os.path.join(os.getcwd(), "..", ".."))
 version = open(os.path.join(project_root, "VERSION")).read().strip()
 # The full version, including alpha/beta/rc tags
 release = version
 
-_docdir = os.path.realpath(os.getcwd())
-_srcdir = os.path.realpath(os.path.join(os.getcwd(), ".."))
-_sitedir = os.path.realpath(os.path.join(os.getcwd(), "..", "site"))
-_staticdir = os.path.realpath(os.path.join(_docdir, "_static"))
-_templatedir = os.path.realpath(os.path.join(_docdir, "_templates"))
-
-if not os.path.exists(_staticdir):
-    os.makedirs(_staticdir)
-
-if not os.path.exists(_templatedir):
-    os.makedirs(_templatedir)
-
-
 # -- General configuration ---------------------------------------------------
 
-install("sphinx_rtd_theme")
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
-    "sphinx.ext.todo",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.napoleon",
-    "sphinx_markdown_tables",
-    "recommonmark",
-    "sphinxcontrib.doxylink",
+    "rocm_docs",
+    "rocm_docs.doxygen",
 ]
 
-source_suffix = {
-    ".rst": "restructuredtext",
-    ".md": "markdown",
+doxygen_root = "."
+doxysphinx_enabled = True
+doxygen_project = {
+    "name": "rocprofiler-sdk",
+    "path": "_doxygen/xml",
 }
+doxyfile = "rocprofiler-sdk.dox"
 
-from recommonmark.parser import CommonMarkParser
+external_projects_current_project = "rocprofiler-sdk"
+external_projects = []
 
-source_parsers = {".md": CommonMarkParser}
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The master toctree document.
 master_doc = "index"
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+external_toc_path = "./_toc.yml"
 
-default_role = None
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+suppress_warnings = ["etoc.toctree"]
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = "sphinx_rtd_theme"
+
+html_theme = "rocm_docs_theme"
+html_theme_options = {"flavor": "rocm"}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
-html_theme_options = {
-    # "analytics_id": "G-...",  #  Provided by Google in your dashboard
-    "logo_only": False,
-    "display_version": True,
-    "prev_next_buttons_location": "bottom",
-    "style_external_links": False,
-    # 'style_nav_header_background': 'white',
-    # Toc options
-    "collapse_navigation": True,
-    "sticky_navigation": True,
-    "navigation_depth": 4,
-    "includehidden": True,
-    "titles_only": False,
-}
-
-doxygen_root = "_doxygen"  # this is just a convenience variable
-doxylink = {
-    "demo": (  # "demo" is the role name that you can later use in sphinx to reference this doxygen documentation (see below)
-        f"{doxygen_root}/tagfile.xml",  # the first parameter of this tuple is the tagfile
-        f"{doxygen_root}/html",  # the second parameter of this tuple is a relative path pointing from
-        # sphinx output directory to the doxygen output folder inside the output
-        # directory tree.
-        # Doxylink will use the tagfile to get the html file name of the symbol you want
-        # to link and then prefix it with this path to generate html links (<a>-tags).
-    ),
-}
-
-from pygments.styles import get_all_styles
-
-# The name of the Pygments (syntax highlighting) style to use.
-styles = list(get_all_styles())
-preferences = ("emacs", "pastie", "colorful")
-for pref in preferences:
-    if pref in styles:
-        pygments_style = pref
-        break
-
-from recommonmark.transform import AutoStructify
-
-
-# app setup hook
-def setup(app):
-    app.add_config_value(
-        "recommonmark_config",
-        {
-            "auto_toc_tree_section": "Contents",
-            "enable_eval_rst": True,
-            "enable_auto_doc_ref": False,
-        },
-        True,
-    )
-    app.add_transform(AutoStructify)
+html_title = f"ROCprofiler-SDK {version} Documentation"

source/docs/environment.yml

@@ -127,16 +127,4 @@ dependencies:
   - zlib=1.2.13=hd590300_5
   - zstd=1.5.5=hfc55251_0
   - pip:
-      - click==8.1.7
-      - click-log==0.4.0
-      - doxysphinx==3.3.4
-      - libsass==0.22.0
-      - lxml==4.9.3
-      - mpire==2.8.0
-      - pyjson5==1.6.4
-      - pyparsing==3.1.1
-      - python-dateutil==2.8.2
-      - six==1.16.0
-      - sphinx-markdown==1.0.2
-      - sphinxcontrib-doxylink==1.12.2
-      - tqdm==4.66.1
+      - -r ./sphinx/requirements.txt

source/docs/features.md

@@ -1,11 +1,5 @@
 # Features
 
-```eval_rst
-.. toctree::
-   :glob:
-   :maxdepth: 4
-```
-
 ## Overview
 
 - Improved tool initialization