Build online docs, and upload to ReadtheDocs

.github/workflows/build.yml

@@ -277,6 +277,14 @@ jobs:
           # don't use $(pwd) to get abspath, not valid on Windows
           echo "EXAMPLE_COPY_PATH=${{ env.PACK_NAME }}/test_tmp" >> $GITHUB_ENV
 
+      - name: Test compare_c_py
+        working-directory: ${{ env.EXAMPLE_COPY_PATH }}/compare_c_py
+        run: |
+          # 检查C程序和Python程序的计算结果是否一致
+          chmod +x *.sh
+          ./run_grt.sh
+          python run_pygrt.py
+
       - name: Test 1 compare_results
         working-directory: ${{ env.EXAMPLE_COPY_PATH }}/compare_results
         run: |

.gitignore

@@ -10,7 +10,6 @@
 
 
 /for_paper
-/docs
 
 /pygrt/C_extension/build/
 /pygrt/C_extension/lib/

.readthedocs.yaml

@@ -0,0 +1,43 @@
+# Read the Docs configuration file for Sphinx projects
+# 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.10"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+  apt_packages: ["doxygen"]
+
+  commands:
+    - cd docs && chmod +x *.sh && ./compile.sh
+
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# 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
+
+

docs/Makefile

@@ -0,0 +1,24 @@
+# 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     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm $(BUILDDIR)/* -rf
+	rm doxygen_h/* -rf
+
+.PHONY: help Makefile clean
+
+# 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/compile.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+chmod +x *.sh
+
+# 清空
+make clean
+
+# 生成api对应的.rst文件
+./create_api_rst.sh
+
+# 执行doxygen
+doxygen doxyfile_h
+
+# 构建
+make html
+# sphinx-autobuild --port 8000 source build

docs/create_api_rst.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+
+# 根据源代码中include/路径下的.h文件，自动在source/API/C_extension文件夹下生成.rst文件
+
+APIDIR="source/API"
+
+PDIR="$APIDIR/C_extension"
+rm -rf $PDIR
+mkdir -p $PDIR 
+
+SDIR="../pygrt/C_extension/include"
+
+c_api_rst="$APIDIR/c_api.rst"
+
+cat > $c_api_rst <<EOF
+C extension API
+===============================
+
+:Author: Zhu Dengda
+:Email:  zhudengda@mail.iggcas.ac.cn
+
+-----------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+EOF
+
+for dir1 in $(ls $SDIR); do
+    mkdir -p $PDIR/$dir1
+    cat > $PDIR/$dir1.rst <<EOF
+$dir1
+=========================================
+
+.. toctree::
+   :maxdepth: 2
+
+EOF
+    for hnm in $(ls $SDIR/$dir1); do
+        cat > $PDIR/$dir1/${hnm%%.*}.rst <<EOF
+$hnm
+--------------------------------------
+
+.. doxygenfile:: $hnm
+    :project: h_PyGRT
+EOF
+
+    echo "   $dir1/${hnm%%.*}" >> $PDIR/$dir1.rst
+    done
+
+    echo "   C_extension/$dir1" >> $c_api_rst
+done
+
+
+
+# 根据源代码中pygrt/路径下的.py文件，自动在source/API/pygrt文件夹下生成.rst文件
+PDIR="$APIDIR/pygrt"
+rm -rf $PDIR
+mkdir -p $PDIR 
+
+SDIR="../pygrt"
+
+py_api_rst="$APIDIR/py_api.rst"
+
+cat > $py_api_rst <<EOF
+**PyGRT** package API
+========================
+
+:Author: Zhu Dengda
+:Email:  zhudengda@mail.iggcas.ac.cn
+
+-----------------------------------------------------------
+
+
+.. toctree::
+   :maxdepth: 2
+
+EOF
+
+for py in $(ls -1 $SDIR/*.py | xargs -n1 basename); do
+    if [[ "$py" == "__init__.py" || "$py" == "_version.py" || "$py" == "print.py" ]]; then
+        continue
+    fi
+
+    cat > $PDIR/${py%%.*}.rst <<EOF
+pygrt.${py%%.*}
+--------------------------------------
+
+.. automodule:: pygrt.${py%%.*}
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+EOF
+
+    echo "   pygrt/${py%%.*}" >> $py_api_rst
+
+done

docs/doxyfile_h

@@ -0,0 +1,32 @@
+# 头文件配置文档 
+
+# The INPUT tag is used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT = ../pygrt/C_extension/include 
+
+RECURSIVE = YES
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank, Doxygen will consider all files in the directories.
+
+FILE_PATTERNS = *.h
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+
+OUTPUT_DIRECTORY = ./doxygen_h
+
+# If the GENERATE_XML tag is set to YES Doxygen will generate an XML file
+# that captures the structure of the code including all documentation.
+
+GENERATE_XML = YES
+
+# Doxyfile Configuration
+USE_MATHJAX = YES
+
+MARKDOWN_SUPPORT = YES

docs/requirements.txt

@@ -0,0 +1,15 @@
+breathe
+commonmark
+recommonmark
+sphinx
+sphinx-rtd-theme
+sphinx-copybutton
+sphinx_markdown_tables
+sphinxcontrib-mermaid
+sphinxcontrib-htmlhelp
+sphinxcontrib-jsmath
+nbsphinx
+graphviz
+sphinx-tabs
+setuptools-scm  # 自动从git tag中构建版本
+# git+https://github.com/Dengda98/PyGRT.git  # 包本身

docs/source/API/api.rst

@@ -0,0 +1,13 @@
+API
+==================
+
+:Author: Zhu Dengda
+:Email:  zhudengda@mail.iggcas.ac.cn
+
+-----------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   c_api
+   py_api

docs/source/API/c_api.rst

@@ -0,0 +1,15 @@
+C extension API
+===============================
+
+:Author: Zhu Dengda
+:Email:  zhudengda@mail.iggcas.ac.cn
+
+-----------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   C_extension/common
+   C_extension/dynamic
+   C_extension/static
+   C_extension/travt

docs/source/API/py_api.rst

@@ -0,0 +1,18 @@
+**PyGRT** package API
+========================
+
+:Author: Zhu Dengda
+:Email:  zhudengda@mail.iggcas.ac.cn
+
+-----------------------------------------------------------
+
+
+.. toctree::
+   :maxdepth: 2
+
+   pygrt/c_interfaces
+   pygrt/c_structures
+   pygrt/pygrn
+   pygrt/pymod
+   pygrt/signals
+   pygrt/utils