Create .readthedocs.yaml (#94)

* Create .readthedocs.yaml * Post Doxygen generated documentation to the readthedocs * Update conf.py * Update Doxyfile.in * Update index.rst --------- Co-authored-by: [email protected] <[email protected]> Co-authored-by: [email protected] <[email protected]>
ORNL · Dec 4, 2023 · 2d2b21a · 2d2b21a
1 parent 4c009e6
commit 2d2b21a
Show file tree

Hide file tree

Showing 7 changed files with 112 additions and 47 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,40 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+  apt_packages:
+    - ghostscript
+    - graphviz
+  jobs:
+    post_build:
+    - cd docs && doxygen ./doxygen/Doxyfile.in 
+# checks for broken links sometimes it gives false negatives
+#    - python -m sphinx -b linkcheck -D linkcheck_timeout=1 docs/ $READTHEDOCS_OUTPUT/linkcheck
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: docs/requirements.txt
diff --git a/docs/conf.py b/docs/conf.py
@@ -16,20 +16,23 @@
 import os
 import shlex
 
-# Call doxygen in ReadtheDocs
-# read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
-# if read_the_docs_build:
+
 
 # Modify Doxyfile for ReadTheDocs compatibility
 with open('./doxygen/Doxyfile.in', 'r') as f:
     fdata = f.read()
 fdata = fdata.replace('@PROJECT_SOURCE_DIR@', '.')
 with open('./doxygen/Doxyfile.in', 'w') as f:
     f.write(fdata)
-
-# Call doxygen
-from subprocess import call
-call(['doxygen', "./doxygen/Doxyfile.in"])
+# The output directory needs to point to a directory within ../_readthedocs/ 
+# by default readthedocs checks for html files within ../_readthedocs/ folder
+# ../readthedocs folder does not exist locally only on the readthedocs server.
+with open('./doxygen/Doxyfile.in', 'a') as f:
+    f.write("\nOUTPUT_DIRECTORY=../_readthedocs/html/doxygen")
+
+        # Call doxygen
+    # from subprocess import call
+    # call(['doxygen', "./doxygen/Doxyfile.in"])
 
 
 # Get current directory
@@ -69,7 +72,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.html']
+source_suffix = ['.rst']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -82,21 +85,8 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
-
-templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
-root_doc = 'index'
-
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = 'alabaster'
-html_static_path = ['_static']
-
-
 # -- Option for numbering figures/tables/etc.-----------------------------------
 # Note: numfig requires Sphinx (1.3+)
 numfig = True
@@ -194,7 +184,12 @@
 # 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 = [os.path.join(conf_directory, 'sphinx/_static')]
+
+# all static files should be in the _build/_static directory
+# readthedocs server checks out the github repo and paths remain the same
+html_static_path = [os.path.join(conf_directory, 'sphinx/_build/_static')]
+
+#html_static_path = ['docs/sphinx/_build/_static/theme_overrides.css']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -263,7 +258,7 @@
 # override wide tables in RTD theme
 # (Thanks to https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html)
 # These folders are copied to the documentation's HTML output
-html_static_path = ['sphinx/_static/theme_overrides.css']
+# html_static_path = ['sphinx/_static']
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)

diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in
@@ -78,7 +78,7 @@ PROJECT_ICON           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = sphinx/_build/doxygen
+# OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/html/doxygen
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -2716,7 +2716,7 @@ DOT_PATH               =
 # command).
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOTFILE_DIRS           = @PROJECT_SOURCE_DIR@/docs
+DOTFILE_DIRS           = 
 
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
@@ -2845,4 +2845,4 @@ GENERATE_TREEVIEW      = YES # required!
 DISABLE_INDEX          = NO
 FULL_SIDEBAR           = NO
 HTML_EXTRA_STYLESHEET  = doxygen/doxygen-awesome.css
-HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
+HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
diff --git a/docs/doxygen/index.rst b/docs/doxygen/index.rst
@@ -1,22 +1,8 @@
 
-Source Documentation
-====================
-
 API Documentation
------------------
-
-Doxygen generated API documentation can be found here: `API documentation <html/index.html>`_
-
-`Coo_8cpp documentation <html/Coo_8cpp.html>`_
-
-`Csc_8cpp documentation <html/Csc_8cpp.htmll>`_
-
-`Csr_8cpp documentation <html/Csr_8cpp.html>`_
+====================
 
-`GramSchmidt_8cpp documentation <html/GramSchmidt_8cpp.html>`_
 
-`LinAlgWorkspaceCUDA_8cpp documentation <html/LinAlgWorkspaceCUDA_8cpp.html>`_
+Doxygen generated API documentation can be found here: `Doxygen Docs <html/index.html>`_
 
-`LinAlgWorkspaceHIP_8cpp documentation <html/LinAlgWorkspaceHIP_8cpp.html>`_
 
-`LinAlgWorkspaceCpu_8cpp documentation <./html/LinAlgWorkspaceCpu_8cpp.html>`_
diff --git a/docs/index.rst b/docs/index.rst
@@ -69,7 +69,7 @@ Documentation
 
 User guides and source code documentation are always linked on this site.
 `ReSolve Github Project <https://github.com/ORNL/ReSolve>`_.
-`Source documentation <doxygen/html/index.html>`_
+`Source documentation <html/index.html>`_
 
 .. list-table::
    :align: center
@@ -84,7 +84,7 @@ Contributing
 ------------
 
 For all contributions to ReSolve please follow the `developer
-guidelines <CONTRIBUTING.md>`__
+guidelines <sphinx/coding_guide/index.html>`__
 
 Test and Deploy
 ---------------
@@ -183,8 +183,8 @@ License
 Copyright © 2023, UT-Battelle, LLC, and Battelle Memorial Institute.
 
 ReSolve is a free software distributed under a BSD-style license. See
-the `LICENSE <LICENSE>`__ and `NOTICE <NOTICE>`__ files for details. All
-new contributions to ReSolve must be made under the smae licensing
+the `LICENSE <sphinx/license.rst>`__ and `NOTICE <sphinx/notice.rst>`__ files for details. All
+new contributions to ReSolve must be made under the same licensing
 terms.
 
 
@@ -194,5 +194,6 @@ terms.
    :caption: Developer Resources
 
    sphinx/coding_guide/index
-   sphinx/licenses
    doxygen/index
+   sphinx/licenses
+   sphinx/notice 
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,5 @@
+docutils
+sphinx==6.2.1
+sphinx-rtd-theme==1.2.2
+breathe 
+m2r2
diff --git a/docs/sphinx/notice.rst b/docs/sphinx/notice.rst
@@ -0,0 +1,38 @@
+Notice
+*******
+
+Disclaimer:
+
+This material was prepared as an account of work sponsored by an agency of the
+United States Government.  Neither the United States Government nor the United
+States Department of Energy, nor UT-Battelle, nor Battelle Memorial Institute
+nor any of their employees, nor any jurisdiction or organization that has
+cooperated in the development of these materials, makes any warranty, express
+or implied, or assumes any legal liability or responsibility for the accuracy,
+completeness, or usefulness or any information, apparatus, product, software,
+or process disclosed, or represents that its use would not infringe privately
+owned rights.
+
+Reference herein to any specific commercial product, process, or service by
+trade name, trademark, manufacturer, or otherwise does not necessarily
+constitute or imply its endorsement, recommendation, or favoring by the United
+States Government or any agency thereof, or UT Batelle or Battelle Memorial
+Institute. The views and opinions of authors expressed herein do not
+necessarily state or reflect those of the United States Government or any
+agency thereof.
+
+                     OAK RIDGE NATIONAL LABORATORY
+                              operated by
+                              UT-BATTELLE
+                                for the
+                   UNITED STATES DEPARTMENT OF ENERGY
+                    under Contract DE-AC05-00OR22725
+
+                                  and
+
+                  PACIFIC NORTHWEST NATIONAL LABORATORY
+                              operated by
+                       BATTELLE MEMORIAL INSTITUTE
+                                for the
+                   UNITED STATES DEPARTMENT OF ENERGY
+                    under Contract DE-AC05-76RL01830