Skip to content

Commit

Permalink
readthedocs updates (#877)
Browse files Browse the repository at this point in the history
* 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>
  • Loading branch information
bgopesh and samjwu authored Jun 21, 2024
1 parent 12785ad commit a60c4de
Show file tree
Hide file tree
Showing 23 changed files with 305 additions and 234 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down
21 changes: 21 additions & 0 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions source/docs/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,5 @@
/_doxygen
/.gitinfo
/*.dox
/.sass-cache
/_toc.yml
2 changes: 1 addition & 1 deletion source/docs/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
23 changes: 23 additions & 0 deletions source/docs/_toc.yml.in
Original file line number Diff line number Diff line change
@@ -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
34 changes: 0 additions & 34 deletions source/docs/about.md

This file was deleted.

6 changes: 0 additions & 6 deletions source/docs/buffered_services.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
6 changes: 0 additions & 6 deletions source/docs/callback_services.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,5 @@
# Callback Tracing Services

```eval_rst
.. toctree::
:glob:
:maxdepth: 4
```

## Overview

## Code Object Tracing
Expand Down
146 changes: 45 additions & 101 deletions source/docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"
12 changes: 0 additions & 12 deletions source/docs/developer_api.md

This file was deleted.

14 changes: 1 addition & 13 deletions source/docs/environment.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
6 changes: 0 additions & 6 deletions source/docs/features.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,5 @@
# Features

```eval_rst
.. toctree::
:glob:
:maxdepth: 4
```

## Overview

- Improved tool initialization
Expand Down
Loading

0 comments on commit a60c4de

Please sign in to comment.