From 86cab08bd0edebb6b65c3f5b204a29930ebe41db Mon Sep 17 00:00:00 2001
From: Ian Bell <ian.bell@nist.gov>
Date: Mon, 7 Nov 2022 09:56:15 -0500
Subject: [PATCH] Add doxygen docs to build
See #25
---
.gitignore | 4 +++-
.readthedocs.yml | 5 ++++-
doc/environment.yml | 20 ++++++++++++++++++++
doc/source/conf.py | 13 +++++++++++--
4 files changed, 38 insertions(+), 4 deletions(-)
create mode 100644 doc/environment.yml
diff --git a/.gitignore b/.gitignore
index 1c5289f..639ebfb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,4 +9,6 @@
/dev/docker/valgrind/output
/dev/docker/gcov/output
/**/.ipynb_checkpoints
-/doc/build
\ No newline at end of file
+/doc/build
+doc/source/_static/doxygen
+doc/source/api/*.rst
\ No newline at end of file
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 268e96a..3b4788c 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -5,6 +5,9 @@
# Required
version: 2
+conda:
+ environment: doc/environment.yml
+
# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
@@ -26,4 +29,4 @@ sphinx:
# Optionally declare the Python requirements required to build your docs
python:
install:
- - requirements: doc/requirements.txt
\ No newline at end of file
+ - requirements: doc/requirements.txt
diff --git a/doc/environment.yml b/doc/environment.yml
new file mode 100644
index 0000000..3f99900
--- /dev/null
+++ b/doc/environment.yml
@@ -0,0 +1,20 @@
+# This .yml file is used to specify the conda environment that should be loaded into the RTD instance
+name: teqpdocs
+dependencies:
+ - python=3.10
+ - pip
+ - doxygen
+ - cmake
+ - pip:
+ - breathe
+ - teqp
+ - numpy
+ - scipy
+ - jupyter
+ - notebook
+ - nbconvert
+ - nbsphinx
+ - pandas
+ - matplotlib
+ - PCSAFTsuperanc
+ - sphinxcontrib-doxylink
\ No newline at end of file
diff --git a/doc/source/conf.py b/doc/source/conf.py
index c0474e6..3525a79 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -36,6 +36,10 @@ if on_rtd:
if file.endswith('.ipynb') and '.ipynb_checkpoints' not in path:
subprocess.check_output(f'jupyter nbconvert --to notebook --output {file} --execute {file}', shell=True, cwd=path)
# --ExecutePreprocessor.allow_errors=True (this allows you to allow errors globally, but a raises-exception cell tag is better)
+# Run doxygen
+if not os.path.exists('source/_static/'):
+ os.makedirs('source/_static')
+subprocess.check_call('doxygen', cwd='..', shell=True)
### -- Auto-generate API documentation -----------------------------------------
here = os.path.dirname(__file__)
@@ -48,7 +52,8 @@ subprocess.check_output(f'sphinx-apidoc -f -o api {os.path.dirname(teqp.__file__
# ones.
extensions = [
'nbsphinx',
-'sphinx.ext.autodoc'
+'sphinx.ext.autodoc',
+'sphinxcontrib.doxylink',
]
# Add any paths that contain templates here, relative to this directory.
@@ -59,6 +64,10 @@ templates_path = ['_templates']
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
+doxylink = {
+ 'teqp' : ('source/_static/doxygen/html/teqp.tag', '_static/doxygen/html'),
+}
+
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -72,4 +81,4 @@ else:
# 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']
\ No newline at end of file
+html_static_path = ['_static']
--
GitLab