Docs skeleton (#51)

* Add doxygen-awesome-css submodule

* Basic documentation files

- conf.py: run by sphinx
- about.md: info about rocprofiler
- features.md: overview of features
- installation.md: build/test/install instructions
- index.md: sets up main page
- generate-doxyfile.cmake: generates rocprofiler.dox with rocprofiler-specific info
- environment.yml: conda environment
- Makefile: sphinx makefile
- README.md: build instructions
- rocprofiler.dox.in: doxygen template
- .gitignore: ignores generated files
- .nojekyll: prevents GitHub Pages from using Jekyll for deployment of pages

* Documentation scripts

- scripts for doing common sequences of commands for building docs
- update-docs.sh: builds the docs and installs the docs if /docs directory is present
- update-doxygen.sh: quick script for generating doxygen

* Workflow for docs

- step for building docs
- step for deploying docs

* Update doxygen comments in include/rocprofiler

- rocprofiler.h / rocprofiler_plugins.h
  - fixed non-existent global references in doxygen comments
  - fixed parameter names that were incorrect or not updated

* Update docs workflow

- only deploy docs when on main branch

source/scripts/update-docs.sh

@@ -0,0 +1,39 @@
+#!/bin/bash -e
+
+message()
+{
+    echo -e "\n\n##### ${@}... #####\n"
+}
+
+WORK_DIR=$(cd $(dirname ${BASH_SOURCE[0]})/../docs &> /dev/null && pwd)
+SOURCE_DIR=$(cd ${WORK_DIR}/../.. &> /dev/null && pwd)
+
+message "Working directory is ${WORK_DIR}"
+message "Source directory is ${SOURCE_DIR}"
+
+message "Changing directory to ${WORK_DIR}"
+cd ${WORK_DIR}
+
+message "Generating rocprofiler.dox"
+cmake -DSOURCE_DIR=${SOURCE_DIR} -P ${WORK_DIR}/generate-doxyfile.cmake
+
+message "Generating doxygen xml files"
+doxygen rocprofiler.dox
+doxygen rocprofiler.dox
+
+message "Running doxysphinx"
+doxysphinx build ${WORK_DIR} ${WORK_DIR}/_build/html ${WORK_DIR}/_doxygen/html
+
+message "Building html documentation"
+make html SPHINXOPTS="-W --keep-going -n"
+
+if [ -d ${SOURCE_DIR}/docs ]; then
+    message "Removing stale documentation in ${SOURCE_DIR}/docs/"
+    rm -rf ${SOURCE_DIR}/docs/*
+
+    message "Adding nojekyll to docs/"
+    cp -r ${WORK_DIR}/.nojekyll ${SOURCE_DIR}/docs/.nojekyll
+
+    message "Copying source/docs/_build/html/* to docs/"
+    cp -r ${WORK_DIR}/_build/html/* ${SOURCE_DIR}/docs/
+fi

source/scripts/update-doxygen.sh

@@ -0,0 +1,10 @@
+#!/bin/bash -e
+
+WORK_DIR=$(cd $(dirname ${BASH_SOURCE[0]})/../docs &> /dev/null && pwd)
+SOURCE_DIR=$(cd ${WORK_DIR}/../.. &> /dev/null && pwd)
+
+cmake -DSOURCE_DIR=${SOURCE_DIR} -P generate-doxyfile.cmake
+
+doxygen rocprofiler.dox
+
+doxysphinx build ${WORK_DIR} ${WORK_DIR}/_build/html ${WORK_DIR}/_doxygen/html