diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..a2886ecf --- /dev/null +++ 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 index ad2b34fa..a8154002 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,9 +16,7 @@ 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: @@ -26,10 +24,15 @@ 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 index 470dcf90..b5024d27 100644 --- 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 \ No newline at end of file +HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5 diff --git a/docs/doxygen/index.rst b/docs/doxygen/index.rst index 212510af..3808c9f9 100644 --- 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 `_ - -`Coo_8cpp documentation `_ - -`Csc_8cpp documentation `_ - -`Csr_8cpp documentation `_ +==================== -`GramSchmidt_8cpp documentation `_ -`LinAlgWorkspaceCUDA_8cpp documentation `_ +Doxygen generated API documentation can be found here: `Doxygen Docs `_ -`LinAlgWorkspaceHIP_8cpp documentation `_ -`LinAlgWorkspaceCpu_8cpp documentation <./html/LinAlgWorkspaceCpu_8cpp.html>`_ diff --git a/docs/index.rst b/docs/index.rst index 43bcf885..f32240bd 100644 --- 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 `_. -`Source documentation `_ +`Source documentation `_ .. list-table:: :align: center @@ -84,7 +84,7 @@ Contributing ------------ For all contributions to ReSolve please follow the `developer -guidelines `__ +guidelines `__ 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 `__ and `NOTICE `__ files for details. All -new contributions to ReSolve must be made under the smae licensing +the `LICENSE `__ and `NOTICE `__ 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 new file mode 100644 index 00000000..52330aba --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +docutils +sphinx==6.2.1 +sphinx-rtd-theme==1.2.2 +breathe +m2r2 \ No newline at end of file diff --git a/docs/sphinx/notice.rst b/docs/sphinx/notice.rst new file mode 100644 index 00000000..ac552234 --- /dev/null +++ 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