Merge pull request #14 from robertmaynard/add_documentation_generation

Add support for building sphinx based documentation for the project

.gitignore

@@ -4,6 +4,7 @@
 ## C++ test build directory
 build/
 example/build/
+docs/_build
 
 ## Eclipse IDE
 .project

README.md

@@ -83,22 +83,14 @@ The most commonly used function are:
 The `rapids-export` module contains core functionality to allow projects to easily record and write out
 build and install dependencies, that come from `find_package` or `cpm`
 
-- `rapids_export_package(<type> <package_name> <export_set>)` Explicitly record a `find_package` call for `install`
-  or `build` exporting. Used by `rapids_export` to generate a correct config module.
-- `rapids_export_cpm(<type> <package_name> <export_set>)` Explicitly record a `cpm` call for `install` or `build`
-  exporting. Used by `rapids_export` to generate a correct config module.
-- `rapids_export_find_package_file(<type> <file_path> <export_set>)` Explicitly record a custom `Find<Pkg>.cmake`
-  file that is required for the `install` or `build` export set. Used by `rapids_export` to correctly install
-  custom FindModules.
-- `rapids_export(<type> <project> EXPORT_SET <name>)` write out all the require components of a projects config
-  module so that the `install` or `build` directory can be imported via `find_package`. See `rapids_export`
-  documentation for full documentation
+- `rapids_export(<type> <project> EXPORT_SET <name>)` write out all the require components of a
+  projects config module so that the `install` or `build` directory can be imported via `find_package`. See `rapids_export` documentation for full documentation
 
 
 ### find
 
-The `rapids-find` module contains core functionality to allow projects to easily generate FindModule or export
-`find_package` calls:
+The `rapids-find` module contains core functionality to allow projects to easily generate FindModule
+or export `find_package` calls:
 
 The most commonly used function are:
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+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
+
+# 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)

docs/api.rst

@@ -0,0 +1,87 @@
+API Reference
+#############
+
+
+Common
+******
+
+The `rapids_cmake` functions provide common CMake logic that numerous projects
+require.
+
+.. toctree::
+   :titlesonly:
+
+   /command/rapids_cmake_build_type
+   /command/rapids_cmake_make_global
+   /command/rapids_cmake_support_conda_env
+
+CPM
+***
+
+The `rapids_cpm` functions allow projects to find or build dependencies with built-in
+tracking of these dependencies for correct export support.
+
+.. toctree::
+   :titlesonly:
+
+   /command/rapids_cpm_init
+   /command/rapids_cpm_find
+
+Find
+****
+
+The `rapids_find` functions allow projects to find system dependencies with built-in
+tracking of these dependencies for correct export support.
+
+.. toctree::
+   :titlesonly:
+
+   /command/rapids_find_generate_module
+   /command/rapids_find_package
+
+CUDA
+****
+
+The `rapids_cuda` functions provide common CMake CUDA logic that numerous projects
+require.
+
+.. toctree::
+   :titlesonly:
+
+    rapids_cuda_init_architectures </command/rapids_cuda_init_architectures>
+    rapids_cuda_init_runtime </command/rapids_cuda_init_runtime>
+    rapids_cuda_set_architectures [Advanced] </command/rapids_cuda_set_architectures>
+
+
+Export Set Generation
+*********************
+
+These `rapids_export` functions allow projects to generate correct build and install tree `Project-Config.cmake` modules including required dependencies.
+
+For the vast majority of projects :cmake:command:`rapids_export` should be sufficient. But when
+not projects may use commands such as :cmake:command:`rapids_write_dependencies` and
+cmake:command:`rapids_write_language` to create a custom `Project-Config.cmake`.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   rapids_export </command/rapids_export>
+   rapids_export_write_dependencies [Advanced] </command/rapids_export_write_dependencies>
+   rapids_export_write_language     [Advanced] </command/rapids_export_write_language>
+
+Export Set Tracking
+*******************
+
+These `rapids_export` functions allow projects to track track dependencies for
+correct export generation. These should only be used when :cmake:command:`rapids_find_package`,
+:cmake:command:`rapids_cpm_find`, or :cmake:command:`rapids_find_generate_module` are insufficient.
+
+
+.. toctree::
+   :titlesonly:
+
+   rapids_export_cpm [Advanced] </command/rapids_export_cpm>
+   rapids_export_find_package_file [Advanced] </command/rapids_export_find_package_file>
+   rapids_export_package [Advanced] </command/rapids_export_package>
+

docs/basics.rst

@@ -0,0 +1,33 @@
+rapids-cmake
+############
+
+This is a collection of CMake modules that are useful for all CUDA RAPIDS
+projects. By sharing the code in a single place it makes rolling out CMake
+fixes easier.
+
+
+Installation
+************
+
+The ``rapids-cmake`` module is designed to be acquired via CMake's `Fetch
+Content <https://cmake.org/cmake/help/latest/module/FetchContent.html>`_ into your project.
+
+.. code-block:: cmake
+
+  cmake_minimum_required(...)
+
+  include(FetchContent)
+  FetchContent_Declare(
+    rapids-cmake
+    GIT_REPOSITORY https://github.com/rapidsai/rapids-cmake.git
+    GIT_TAG        branch-<VERSION_MAJOR>.<VERSION_MINOR>
+  )
+  FetchContent_MakeAvailable(rapids-cmake)
+  include(rapids-cmake)
+  include(rapids-cpm)
+  include(rapids-cuda)
+  include(rapids-export)
+  include(rapids-find)
+
+  project(...)
+

docs/command/rapids_cmake_build_type.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cmake/build_type.cmake

docs/command/rapids_cmake_make_global.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cmake/make_global.cmake

docs/command/rapids_cmake_support_conda_env.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cmake/support_conda_env.cmake

docs/command/rapids_cpm_find.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cpm/find.cmake

docs/command/rapids_cpm_init.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cpm/init.cmake

docs/command/rapids_cuda_init_architectures.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cuda/init_architectures.cmake

docs/command/rapids_cuda_init_runtime.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cuda/init_architectures.cmake

docs/command/rapids_cuda_set_architectures.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/cuda/set_architectures.cmake

docs/command/rapids_export.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/export/export.cmake

docs/command/rapids_export_cpm.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/export/cpm.cmake

docs/command/rapids_export_find_package_file.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/export/find_package_file.cmake

docs/command/rapids_export_package.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/export/package.cmake

docs/command/rapids_export_write_dependencies.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/export/write_dependencies.cmake

docs/command/rapids_export_write_language.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/export/write_language.cmake

docs/command/rapids_find_generate_module.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/find/generate_module.cmake

docs/command/rapids_find_package.rst

@@ -0,0 +1 @@
+.. cmake-module:: ../../rapids-cmake/find/package.cmake

docs/conf.py

@@ -0,0 +1,133 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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
+
+# -- Project information -----------------------------------------------------
+
+project = "rapids-cmake"
+copyright = "2021, NVIDIA"
+author = "NVIDIA"
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = "0.20"
+# The full version, including alpha/beta/rc tags.
+release = "0.20.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# 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.intersphinx",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx_copybutton",
+    "sphinxcontrib.moderncmakedomain"
+]
+
+
+copybutton_prompt_text = ">>> "
+
+ipython_mplbackend = "str"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst']
+source_suffix = {".rst": "restructuredtext"}
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- 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_pydata_theme"
+
+# on_rtd is whether we are on readthedocs.org
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+
+if not on_rtd:
+    # only import and set the theme if we're building docs locally
+    # otherwise, readthedocs.org uses their theme by default,
+    # so no need to specify it
+    import sphinx_rtd_theme
+
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# 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"]
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "rapidscmakedoc"
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {"https://docs.python.org/": None}
+
+# Config numpydoc
+numpydoc_show_inherited_class_members = True
+numpydoc_class_members_toctree = False
+
+autoclass_content = "init"
+
+
+def setup(app):
+    app.add_js_file("copybutton_pydocs.js")
+    app.add_css_file("params.css")
+    app.add_css_file("https://docs.rapids.ai/assets/css/custom.css")

docs/index.rst

@@ -0,0 +1,19 @@
+.. rapids-cmake documentation file
+
+Welcome to rapids-cmake's documentation!
+===============================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   basics.rst
+   api.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

rapids-cmake/cmake/build_type.cmake

@@ -20,26 +20,24 @@ include_guard(GLOBAL)
 rapids_cmake_build_type
 -----------------------
 
-.. versionadded:: 0.20
+.. versionadded:: v21.06.00
 
-Establish the :variable:`CMAKE_BUILD_TYPE` default value for the project if the user
-hasn't specified one and the generator is either Ninja or Makefile.
-
-.. command:: rapids_cmake_build_type
+Establish the :cmake:variable:`CMAKE_BUILD_TYPE` default value.
 
   .. code-block:: cmake
 
     rapids_cmake_build_type(default_type)
 
-  If the generator is `Ninja` or `Makefile` the :variable:`CMAKE_BUILD_TYPE`
-  variable will be established if it doesn't already exist.
+If the generator is `Ninja` or `Makefile` the :cmake:variable:`CMAKE_BUILD_TYPE`
+variable will be established if not explicitly set by the user. This removes
+situations where the `No-Config` / `Empty` build type is used.
 
-  ``default_type``
-      The default build type to use if one doesn't already exist
+``default_type``
+  The default build type to use if one doesn't already exist
 
 Result Variables
 ^^^^^^^^^^^^^^^^
-  CMAKE_BUILD_TYPE will be set to ``default_type`` if not already set
+  :cmake:variable:`CMAKE_BUILD_TYPE` will be set to ``default_type`` if not already set
 
 #]=======================================================================]
 function(rapids_cmake_build_type default_type)