Skip to content

Commit

Permalink
Add Sphinx docs (#126) (#151)
Browse files Browse the repository at this point in the history
* Add basic Sphinx docs based on rocThrust

* Fix Sphinx errors

* Update copyright date

Co-authored-by: Cory Bloor <[email protected]>
  • Loading branch information
stanleytsang-amd and cgmb authored Jun 28, 2021
1 parent e54e8fd commit ec415b2
Show file tree
Hide file tree
Showing 12 changed files with 417 additions and 20 deletions.
7 changes: 3 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@

### Build dirs ###
build/
/docs/_build/

### Docs dirs ###
doc/html/
doc/xml/
doc/latex/
doc/*.tag
/docs/docBin/

# Created by https://www.gitignore.io/api/c++,cmake

Expand Down Expand Up @@ -51,6 +49,7 @@ CMakeFiles
CMakeScripts
Testing
Makefile
!/docs/Makefile
cmake_install.cmake
install_manifest.txt
compile_commands.json
Expand Down
68 changes: 68 additions & 0 deletions .jenkins/staticanalysis.groovy
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
#!/usr/bin/env groovy
// This shared library is available at https://github.com/ROCmSoftwarePlatform/rocJENKINS/
@Library('rocJenkins@pong') _

// This is file for internal AMD use.
// If you are interested in running your own Jenkins, please raise a github issue for assistance.

import com.amd.project.*
import com.amd.docker.*
import java.nio.file.Path

def runCompileCommand(platform, project, jobName, boolean debug=false)
{
project.paths.construct_build_prefix()

def command = """#!/usr/bin/env bash
set -x
${project.paths.project_build_prefix}/docs/run_doc.sh
"""

try
{
platform.runCommand(this, command)
}
catch(e)
{
throw e
}

publishHTML([allowMissing: false,
alwaysLinkToLastBuild: false,
keepAll: false,
reportDir: "${project.paths.project_build_prefix}/docs/_build/html",
reportFiles: "index.html",
reportName: "Documentation",
reportTitles: "Documentation"])
}

def runCI =
{
nodeDetails, jobName->

def prj = new rocProject('hipCUB', 'StaticAnalysis')

// Define test architectures, optional rocm version argument is available
def nodes = new dockerNodes(nodeDetails, jobName, prj)

boolean formatCheck = false
boolean staticAnalysis = true

def compileCommand =
{
platform, project->

runCompileCommand(platform, project, jobName, false)
}

buildProject(prj , formatCheck, nodes.dockerArray, compileCommand, null, null, staticAnalysis)
}

ci: {
String urlJobName = auxiliary.getTopJobName(env.BUILD_URL)

properties(auxiliary.addCommonProperties([pipelineTriggers([cron('0 1 * * 6')])]))
stage(urlJobName) {
runCI([ubuntu18:['any']], urlJobName)
}
}
2 changes: 1 addition & 1 deletion LICENSE.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
Copyright (c) 2010-2011, Duane Merrill. All rights reserved.
Copyright (c) 2011-2018, NVIDIA CORPORATION. All rights reserved.
Modifications Copyright (c) 2019, Advanced Micro Devices, Inc. All rights reserved.
Modifications Copyright (c) 2019-2021, Advanced Micro Devices, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,13 +158,13 @@ cd hipCUB; cd build
## Documentation

```shell
# go to hipCUB doc directory
cd hipCUB; cd doc
# go to hipCUB docs directory
cd hipCUB; cd docs

# run doxygen
doxygen Doxyfile
# run doxygen and sphinx
./run_docs.sh

# open html/index.html
# open docBin/html/index.html

```

Expand Down
36 changes: 26 additions & 10 deletions doc/Doxyfile → docs/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ PROJECT_LOGO =
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.

OUTPUT_DIRECTORY =
OUTPUT_DIRECTORY = docBin

# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
Expand Down Expand Up @@ -152,7 +152,7 @@ FULL_PATH_NAMES = YES
# will be relative from the directory where doxygen is started.
# This tag requires that the tag FULL_PATH_NAMES is set to YES.

STRIP_FROM_PATH =
STRIP_FROM_PATH = ../hipcub/include/

# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
# path mentioned in the documentation of a class, which tells the reader which
Expand Down Expand Up @@ -770,8 +770,22 @@ WARN_LOGFILE =
# directories like /usr/src/myproject. Separate the files or directories with
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.

INPUT = mainpage.dox
#mainpage.dox \
INPUT = ../hipcub/include/hipcub \
../hipcub/include/hipcub/device \
../hipcub/include/hipcub/iterator \
../hipcub/include/hipcub/thread \
../hipcub/include/hipcub/warp \
../hipcub/include/hipcub/block \
../hipcub/include/hipcub/backend \
../hipcub/include/hipcub/backend/cub \
../hipcub/include/hipcub/backend/cub/device \
../hipcub/include/hipcub/backend/rocprim \
../hipcub/include/hipcub/backend/rocprim/device \
../hipcub/include/hipcub/backend/rocprim/iterator \
../hipcub/include/hipcub/backend/rocprim/thread \
../hipcub/include/hipcub/backend/rocprim/warp \
../hipcub/include/hipcub/backend/rocprim/block

# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
Expand Down Expand Up @@ -1884,7 +1898,7 @@ MAN_LINKS = NO
# captures the structure of the code including all documentation.
# The default value is: NO.

GENERATE_XML = yes
GENERATE_XML = YES

# The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
Expand Down Expand Up @@ -1997,7 +2011,7 @@ ENABLE_PREPROCESSING = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

MACRO_EXPANSION = NO
MACRO_EXPANSION = YES

# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
Expand All @@ -2019,7 +2033,7 @@ SEARCH_INCLUDES = YES
# preprocessor.
# This tag requires that the tag SEARCH_INCLUDES is set to YES.

INCLUDE_PATH =
INCLUDE_PATH = ../hipcub/include/hipcub/

# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
# patterns (like *.h and *.hpp) to filter out the header-files in the
Expand All @@ -2037,7 +2051,9 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

PREDEFINED = "DOXYGEN_SHOULD_SKIP_THIS=1"
PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS=1 \
__HIP_PLATFORM_HCC__=1 \
HIPCUB_DEVICE=__device__

# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
Expand All @@ -2056,7 +2072,7 @@ EXPAND_AS_DEFINED =
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

SKIP_FUNCTION_MACROS = YES
SKIP_FUNCTION_MACROS = NO

#---------------------------------------------------------------------------
# Configuration options related to external references
Expand Down Expand Up @@ -2172,7 +2188,7 @@ DOT_NUM_THREADS = 0
# The default value is: Helvetica.
# This tag requires that the tag HAVE_DOT is set to YES.

DOT_FONTNAME = FreeSans
DOT_FONTNAME =

# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
# dot graphs.
Expand Down
24 changes: 24 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = hipCUB
SOURCEDIR = .
BUILDDIR = _build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile clean

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

clean:
rm -rf docBin/ api/
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
Loading

0 comments on commit ec415b2

Please sign in to comment.