Skip to content

Commit 00bc959

Browse files
oleksandr-pavlykoleksandr-pavlyk
authored
Merge pull request #765 from IntelPython/docs/generate_docsv2
Add a script to generate documentation using new Cmake infrastructure
2 parents 0cf7856 + 3b3979e commit 00bc959

File tree

6 files changed

+224
-80
lines changed

6 files changed

+224
-80
lines changed

‎.github/workflows/generate-docs.yml

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -55,31 +55,28 @@ jobs:
5555
with:
5656
fetch-depth: 0
5757
persist-credentials: false
58-
- name: Build dpctl
59-
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
60-
shell: bash -l {0}
61-
run: |
62-
source /opt/intel/oneapi/setvars.sh
63-
python setup.py develop -- -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx -DDPCTL_ENABLE_LO_PROGRAM_CREATION=ON -DDPCTL_DPCPP_HOME_DIR=${BUILD_PREFIX}
64-
python -c "import dpctl; print(dpctl.__version__)" || exit 1
65-
- name: Build docs
58+
- name: Build dpctl+docs
6659
if: ${{ !github.event.pull_request || github.event.action != 'closed' }}
6760
shell: bash -l {0}
6861
run: |
6962
# Ensure that SYCL libraries are on LD_LIBRARY_PATH
7063
source /opt/intel/oneapi/setvars.sh
71-
cd docs
72-
mkdir -p build && cd build && rm -rf *
7364
wget https://github.com/vovkos/doxyrest/releases/download/doxyrest-2.1.2/doxyrest-2.1.2-linux-amd64.tar.xz
7465
tar xf doxyrest-2.1.2-linux-amd64.tar.xz
75-
cmake .. -DDPCTL_USE_MULTIVERSION_TEMPLATE=ON \
76-
-DDPCTL_ENABLE_DOXYREST=ON \
77-
-DDoxyrest_DIR=`pwd`/doxyrest-2.1.2-linux-amd64
78-
make Sphinx || exit 1
79-
cd ..
80-
mv generated_docs/docs ~/docs
66+
python setup.py develop -- \
67+
-G "Unix Makefiles" \
68+
-DCMAKE_BUILD_TYPE=Debug \
69+
-DCMAKE_C_COMPILER:PATH=icx \
70+
-DCMAKE_CXX_COMPILER:PATH=icpx \
71+
-DDPCTL_ENABLE_LO_PROGRAM_CREATION=ON \
72+
-DDPCTL_GENERATE_DOCS=ON \
73+
-DDPCTL_ENABLE_DOXYREST=ON \
74+
-DDoxyrest_DIR=`pwd`/doxyrest-2.1.2-linux-amd64
75+
python -c "import dpctl; print(dpctl.__version__)" || exit 1
76+
cd "$(find _skbuild -name cmake-build)" || exit 1
77+
cmake --build . --target Sphinx || exit 1
78+
mv ../cmake-install/docs/docs ~/docs
8179
git clean -dfx
82-
cd ..
8380
- name: Publish docs
8481
if: ${{ github.ref == 'refs/heads/master' }}
8582
shell: bash -l {0}

‎docs/CMakeLists.txt

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
2-
project("Data-parallel Control (dpctl)")
3-
41
# Option to generate rst for C API and add to Sphinx documentation
52
option(DPCTL_ENABLE_DOXYREST
63
"Enable generation of rst files for C API"
@@ -55,7 +52,6 @@ function(_setup_doxygen)
5552
# Target to generate only Doxygen documentation
5653
add_custom_target(
5754
Doxygen
58-
ALL
5955
DEPENDS ${DOXYGEN_INDEX_FILE}
6056
)
6157
endfunction()
@@ -95,7 +91,6 @@ function(_setup_doxyrest)
9591
# Target to generate rst from Doxygen XML using Doxyrest
9692
add_custom_target(
9793
Doxyrest
98-
ALL
9994
DEPENDS Doxygen ${DOXYREST_OUTPUT}
10095
)
10196
endfunction()
@@ -147,7 +142,6 @@ function(_setup_sphinx)
147142
# important, we want the rst files to generate prior to sphinx build.
148143
add_custom_target(
149144
Sphinx
150-
ALL
151145
DEPENDS
152146
${DEPEND_ON_DOXYREST}
153147
${DPCTL_PYAPI_RST_FILE}
@@ -196,12 +190,7 @@ if (DPCTL_ENABLE_DOXYREST)
196190
endif()
197191

198192
# Set the location where the generated docs are saved
199-
if(DPCTL_DOCGEN_PREFIX)
200-
message(STATUS "Generating dpctl documents in " ${DPCTL_DOCGEN_PREFIX})
201-
set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
202-
else()
203-
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
204-
endif()
193+
set(DOC_OUTPUT_DIR ${CMAKE_INSTALL_PREFIX}/docs)
205194

206195
set(INDEX_NO_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_no_doxyrest.rst.in)
207196
set(INDEX_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_doxyrest.rst.in)

‎docs/README.md

Lines changed: 6 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -32,58 +32,13 @@ sudo apt-get install liblua5.2-dev
3232
Generating the docs
3333
===================
3434

35-
The documentation should be generated using the provided `Cmake` build script.
36-
There are a few configurable options that can be used to select the type of
37-
documentation to generate.
35+
The helper script ``scripts/gen_docs.py`` is the preferred way to generate the
36+
documentation. The generated documentation html pages will be installed to the
37+
``CMAKE_INSTALL_PREFIX/docs`` directory.
3838

39-
Build only Doxygen for C API
4039
----------------------------
4140
```bash
42-
cd dpctl/docs
43-
mkdir -p build
44-
cd build
45-
cmake ..
46-
make Doxygen
41+
python scripts/gen_docs.py --doxyrest-root=<PATH to Doxyrest installation>
4742
```
48-
The above steps will generate the `Doxygen` files at
49-
`dpctl/docs/generated_docs/doxygen/html`. The documentation can also be
50-
generated at a custom location by providing the optional flag
51-
52-
```bash
53-
cd dpctl/docs
54-
mkdir -p build
55-
cd build
56-
cmake .. -DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED>
57-
make Doxygen
58-
```
59-
60-
Build only Sphinx for Python API
61-
--------------------------------
62-
```bash
63-
cd dpctl/docs
64-
mkdir -p build
65-
cd build
66-
cmake .. -DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED>
67-
make Sphinx
68-
```
69-
70-
The `make Sphinx` command will generate only the Python API docs for dpctl.
71-
72-
Build consolidated docs
73-
-----------------------
74-
It is possible to generate a single site with both Python and C API docs. As
75-
mentioned before, `Doxyrest` and `Lua` are required to generate the consolidated
76-
site.
77-
78-
```bash
79-
cd dpctl/docs
80-
mkdir -p build
81-
cd build
82-
cmake .. \
83-
-DDPCTL_ENABLE_DOXYREST=ON \
84-
-DDoxyrest_DIR=<PATH_TO_DOXYREST_INSTALL_DIR> \
85-
-DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED>
86-
make Sphinx
87-
```
88-
The `Doxyrest_DIR` flag is optional, but is needed when Doxyrest is installed in
89-
a non-system location.
43+
To skip generating the documentation for ``libsyclinterface``, the
44+
``--doxyrest-root`` option should be omitted.

‎scripts/build_locally.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
1+
# Data Parallel Control (dpctl)
2+
#
3+
# Copyright 2020-2021 Intel Corporation
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
117
import os
218
import subprocess
319
import sys

‎scripts/gen_coverage.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
1+
# Data Parallel Control (dpctl)
2+
#
3+
# Copyright 2020-2021 Intel Corporation
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
117
import os
218
import subprocess
319
import sys

‎scripts/gen_docs.py

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Data Parallel Control (dpctl)
2+
#
3+
# Copyright 2020-2021 Intel Corporation
4+
#
5+
# Licensed under the Apache License, Version 2.0 (the "License");
6+
# you may not use this file except in compliance with the License.
7+
# You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing, software
12+
# distributed under the License is distributed on an "AS IS" BASIS,
13+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
# See the License for the specific language governing permissions and
15+
# limitations under the License.
16+
17+
import os
18+
import subprocess
19+
import sys
20+
21+
22+
def run(
23+
use_oneapi=True,
24+
c_compiler=None,
25+
cxx_compiler=None,
26+
level_zero=True,
27+
compiler_root=None,
28+
bin_llvm=None,
29+
doxyrest_dir=None,
30+
):
31+
IS_LIN = False
32+
33+
if "linux" in sys.platform:
34+
IS_LIN = True
35+
elif sys.platform in ["win32", "cygwin"]:
36+
pass
37+
else:
38+
assert False, sys.platform + " not supported"
39+
40+
if not IS_LIN:
41+
raise RuntimeError(
42+
"This scripts only supports coverage collection on Linux"
43+
)
44+
setup_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
45+
cmake_args = [
46+
sys.executable,
47+
"setup.py",
48+
"develop",
49+
"--",
50+
"-G",
51+
"Unix Makefiles",
52+
"-DCMAKE_BUILD_TYPE=Debug",
53+
"-DCMAKE_C_COMPILER:PATH=" + c_compiler,
54+
"-DCMAKE_CXX_COMPILER:PATH=" + cxx_compiler,
55+
"-DDPCTL_ENABLE_LO_PROGRAM_CREATION=" + ("ON" if level_zero else "OFF"),
56+
"-DDPCTL_DPCPP_FROM_ONEAPI:BOOL=" + ("ON" if use_oneapi else "OFF"),
57+
"-DDPCTL_GENERATE_DOCS=ON",
58+
]
59+
60+
if doxyrest_dir:
61+
cmake_args.append("-DDPCTL_ENABLE_DOXYREST=ON")
62+
cmake_args.append("-DDoxyrest_DIR=" + doxyrest_dir)
63+
64+
if compiler_root:
65+
cmake_args += [
66+
"-DDPCTL_DPCPP_HOME_DIR:PATH=" + compiler_root,
67+
]
68+
env = None
69+
if bin_llvm:
70+
env = {
71+
"PATH": ":".join((os.environ.get("PATH", ""), bin_llvm)),
72+
}
73+
env.update({k: v for k, v in os.environ.items() if k != "PATH"})
74+
# Install dpctl package
75+
subprocess.check_call(cmake_args, shell=False, cwd=setup_dir, env=env)
76+
# Get the path for the build directory
77+
build_dir = (
78+
subprocess.check_output(
79+
["find", "_skbuild", "-name", "cmake-build"],
80+
cwd=setup_dir,
81+
)
82+
.decode("utf-8")
83+
.strip("\n")
84+
)
85+
# Generate docs
86+
subprocess.check_call(
87+
["cmake", "--build", ".", "--target", "Sphinx"], cwd=build_dir
88+
)
89+
generated_doc_dir = (
90+
subprocess.check_output(
91+
["find", "_skbuild", "-name", "index.html"], cwd=setup_dir
92+
)
93+
.decode("utf-8")
94+
.strip("\n")
95+
)
96+
print("Generated documentation placed under ", generated_doc_dir)
97+
98+
99+
if __name__ == "__main__":
100+
import argparse
101+
102+
parser = argparse.ArgumentParser(
103+
description="Driver to build dpctl and generate coverage"
104+
)
105+
driver = parser.add_argument_group(title="Coverage driver arguments")
106+
driver.add_argument("--c-compiler", help="Name of C compiler", default=None)
107+
driver.add_argument(
108+
"--cxx-compiler", help="Name of C++ compiler", default=None
109+
)
110+
driver.add_argument(
111+
"--not-oneapi",
112+
help="Is one-API installation",
113+
dest="oneapi",
114+
action="store_false",
115+
)
116+
driver.add_argument(
117+
"--compiler-root", type=str, help="Path to compiler home directory"
118+
)
119+
driver.add_argument(
120+
"--no-level-zero",
121+
help="Enable Level Zero support",
122+
dest="level_zero",
123+
action="store_false",
124+
)
125+
driver.add_argument(
126+
"--bin-llvm", help="Path to folder where llvm-cov can be found"
127+
)
128+
driver.add_argument(
129+
"--doxyrest-root",
130+
help=(
131+
"Path to Doxyrest installation to use to generate Sphinx docs"
132+
+ "for libsyclinterface"
133+
),
134+
)
135+
136+
args = parser.parse_args()
137+
138+
if args.oneapi:
139+
args.c_compiler = "icx"
140+
args.cxx_compiler = "icpx"
141+
args.compiler_root = None
142+
icx_path = subprocess.check_output(["which", "icx"])
143+
bin_dir = os.path.dirname(os.path.dirname(icx_path))
144+
args.bin_llvm = os.path.join(bin_dir.decode("utf-8"), "bin-llvm")
145+
else:
146+
args_to_validate = [
147+
"c_compiler",
148+
"cxx_compiler",
149+
"compiler_root",
150+
"bin_llvm",
151+
]
152+
for p in args_to_validate:
153+
arg = getattr(args, p, None)
154+
if not isinstance(arg, str):
155+
opt_name = p.replace("_", "-")
156+
raise RuntimeError(
157+
f"Option {opt_name} must be provided is "
158+
"using non-default DPC++ layout"
159+
)
160+
if not os.path.exists(arg):
161+
raise RuntimeError(f"Path {arg} must exist")
162+
163+
run(
164+
use_oneapi=args.oneapi,
165+
c_compiler=args.c_compiler,
166+
cxx_compiler=args.cxx_compiler,
167+
level_zero=args.level_zero,
168+
compiler_root=args.compiler_root,
169+
bin_llvm=args.bin_llvm,
170+
doxyrest_dir=args.doxyrest_root,
171+
)

0 commit comments

Comments
 (0)