Updated docs to use the ROCm standard (ROCm#276)

* improved api docs * add introduction and installing pages to docs * pin docs dependencies * install deps via requirements.txt * fix typo * Updated docs to the ROCm standard * Updated CHANGELOG.md * Removed redundant FILE_PATTERNS * Fixed requirements * Fixed gitignore --------- Co-authored-by: Robin Voetter <[email protected]> Co-authored-by: Nol Moonen <[email protected]>
StreamHPC · Mar 31, 2023 · acc8f8a · acc8f8a
1 parent 6b5561d
commit acc8f8a
Show file tree

Hide file tree

Showing 21 changed files with 544 additions and 669 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,9 +6,6 @@ doc/html/
 doc/xml/
 doc/latex/
 doc/*.tag
-docs/_build/
-docs/api/
-docs/docBin/
 
 # Created by https://www.gitignore.io/api/c++,cmake
 

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -8,6 +8,7 @@ include:
     file:
       - /defaults.yaml
       - /deps-cmake.yaml
+      - /deps-docs.yaml
       - /deps-rocm.yaml
       - /gpus-rocm.yaml
       - /rules.yaml
@@ -159,17 +160,10 @@ test:package:
     - $SUDO_CMD dpkg -r rocprim-dev
 
 test:doc:
-  image: sphinxdoc/sphinx-latexpdf
-  needs: []
   stage: test
   extends:
+    - .build:docs
     - .rules:test
-  before_script:
-    - $SUDO_CMD apt update -qq
-    - $SUDO_CMD apt install -y -qq doxygen
-    - $SUDO_CMD pip3 install sphinx_rtd_theme breathe exhale
-  script:
-    - bash -x $CI_PROJECT_DIR/docs/run_doc.sh
 
 test:
   stage: test

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,24 +1,14 @@
-# .readthedocs.yml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
-# Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
+formats: [htmlzip]
 
-# Optionally build your docs in additional formats such as PDF and ePub
-formats: all
-
-# Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.7
+  version: 3.8
   install:
-    - requirements: docs/requirements.txt
-
+    - requirements: docs/.sphinx/requirements.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,8 @@ Full documentation for rocThrust is available at [https://rocthrust.readthedocs.
 ## (Unreleased) rocThrust 2.18.0 for ROCm 5.6
 ### Fixed 
 - `lower_bound`, `upper_bound`, and `binary_search` failed to compile for certain types.
+### Changed
+- Updated `docs` directory structure to match the standard of [rocm-docs-core](https://github.com/RadeonOpenCompute/rocm-docs-core).
 
 ## (Unreleased) rocThrust 2.17.0 for ROCm 5.5
 ### Added

diff --git a/README.md b/README.md
@@ -221,6 +221,23 @@ make -j4
 
 Documentation is available [here](https://rocthrust.readthedocs.io/en/latest/).
 
+It can also be build using the following commands:
+
+```shell
+# Go to rocThrust docs directory
+cd rocThrust; cd docs
+
+# Install Python dependencies
+python3 -m pip install -r .sphinx/requirements.txt
+
+# Build the documentation
+python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
+
+# For e.g. serve the HTML docs locally
+cd _build/html
+python3 -m http.server
+```
+
 ## Support
 
 Bugs and feature requests can be reported through [the issue tracker](https://github.com/ROCmSoftwarePlatform/rocThrust/issues).