From 54c3568b56cdc79f9cd3c2d47e19fa0998963ed7 Mon Sep 17 00:00:00 2001
From: "lintao@ihep.ac.cn" <lintao@ihep.ac.cn>
Date: Mon, 19 Aug 2024 14:13:29 +0000
Subject: [PATCH] Prepare the docs
---
.build.ci.sh | 25 +++++--
.gitlab-ci.yml | 13 ++++
.readthedocs.yaml | 13 ++++
build-docs.sh | 20 ++++++
docs/Makefile | 20 ++++++
docs/make.bat | 35 ++++++++++
docs/requirements.txt | 3 +
docs/source/analysis/overview.md | 3 +
docs/source/calo/overview.md | 3 +
docs/source/conf.py | 42 ++++++++++++
docs/source/data/overview.md | 3 +
docs/source/dcomputing/overview.md | 3 +
docs/source/development/overview.md | 3 +
docs/source/framework/overview.md | 3 +
docs/source/generator/overview.md | 3 +
docs/source/index.rst | 98 ++++++++++++++++++++++++++++
docs/source/pid/overview.md | 3 +
docs/source/quickstart/quickstart.md | 10 +++
docs/source/releasenotes/overview.md | 3 +
docs/source/simulation/overview.md | 3 +
docs/source/tracking/overview.md | 3 +
21 files changed, 308 insertions(+), 4 deletions(-)
create mode 100644 .readthedocs.yaml
create mode 100755 build-docs.sh
create mode 100644 docs/Makefile
create mode 100644 docs/make.bat
create mode 100644 docs/requirements.txt
create mode 100644 docs/source/analysis/overview.md
create mode 100644 docs/source/calo/overview.md
create mode 100644 docs/source/conf.py
create mode 100644 docs/source/data/overview.md
create mode 100644 docs/source/dcomputing/overview.md
create mode 100644 docs/source/development/overview.md
create mode 100644 docs/source/framework/overview.md
create mode 100644 docs/source/generator/overview.md
create mode 100644 docs/source/index.rst
create mode 100644 docs/source/pid/overview.md
create mode 100644 docs/source/quickstart/quickstart.md
create mode 100644 docs/source/releasenotes/overview.md
create mode 100644 docs/source/simulation/overview.md
create mode 100644 docs/source/tracking/overview.md
diff --git a/.build.ci.sh b/.build.ci.sh
index 3710b9a6..ccea1de5 100755
--- a/.build.ci.sh
+++ b/.build.ci.sh
@@ -1,5 +1,8 @@
#!/bin/bash
-# This is wrapper to run the build.sh on CI
+# This is wrapper to run the build.sh or build-xyz.sh on CI
+
+# The build mode is the suffix in build-xyz.sh
+export BUILD_CI_MODE=${1}
echo "CEPCSW_LCG_RELEASE: ${CEPCSW_LCG_RELEASE}"
echo "CEPCSW_LCG_PLATFORM: ${CEPCSW_LCG_PLATFORM}"
@@ -36,12 +39,26 @@ function build-with-log() {
}
function build-with-stdout() {
+ local build_flags=${BUILD_CI_MODE}
+ local source_flag=true
+
+ # Key4hep stack mode
if [ "$CEPCSW_LCG_RELEASE" = "KEY4HEP_STACK" ]; then
- ./build-k4.sh
- else
+ build_flags=k4
+ source_flag=false
+ fi
+
+ # prepend '-' if necessary
+ if [ -n "$build_flags" ]; then
+ build_flags=-${build_flags}
+ fi
+
+ if $source_flag; then
source setup.sh
- ./build.sh
fi
+
+ ./build${build_flags}.sh
+
}
if [ -n "${GITHUB_ACTION}" ]; then
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 26bfdba7..c5615732 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -62,3 +62,16 @@ build:lcg:el7:
- TDR_o1_v02.tgeo.root
reports:
junit: build.${CEPCSW_LCG_VERSION}.${CEPCSW_LCG_PLATFORM}/cepcsw-ctest-result.xml
+
+##############################################################################
+# Build the docs
+##############################################################################
+build:docs:
+ stage: build
+ tags:
+ - centos7
+ script:
+ - bash ./.build.ci.sh docs
+ artifacts:
+ paths:
+ - docs/build/html/
\ No newline at end of file
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 00000000..9138a7fe
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,13 @@
+version: "2"
+
+build:
+ os: "ubuntu-22.04"
+ tools:
+ python: "3.10"
+
+python:
+ install:
+ - requirements: docs/requirements.txt
+
+sphinx:
+ configuration: docs/source/conf.py
diff --git a/build-docs.sh b/build-docs.sh
new file mode 100755
index 00000000..6ab5cd7a
--- /dev/null
+++ b/build-docs.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+# Description:
+# This script is used to build the CEPCSW docs.
+
+function check-sphinx() {
+ which sphinx-build >& /dev/null
+}
+
+function run-build-docs() {
+ pushd docs
+ make html
+ popd
+}
+
+if check-sphinx; then
+ run-build-docs
+else
+ echo "Please setup sphinx before build the docs. " 1>&2
+ exit -1
+fi
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 00000000..d0c3cbf1
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# 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)
+
+.PHONY: help Makefile
+
+# 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)
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 00000000..6247f7e2
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 00000000..953e51ec
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
+myst-parser==2.0.0
diff --git a/docs/source/analysis/overview.md b/docs/source/analysis/overview.md
new file mode 100644
index 00000000..21911da0
--- /dev/null
+++ b/docs/source/analysis/overview.md
@@ -0,0 +1,3 @@
+# Analysis tools
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/calo/overview.md b/docs/source/calo/overview.md
new file mode 100644
index 00000000..b5781fb8
--- /dev/null
+++ b/docs/source/calo/overview.md
@@ -0,0 +1,3 @@
+# Calo
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 00000000..45bbfe11
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'CEPCSW Documentation'
+copyright = '2020-2024, CEPCSW'
+author = 'CEPCSW'
+
+release = 'tdr24.3'
+version = 'tdr24.3.1'
+
+# -- General configuration
+
+extensions = [
+ 'sphinx.ext.duration',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.autosummary',
+ 'sphinx.ext.intersphinx',
+ 'myst_parser'
+]
+
+source_suffix = {
+ '.rst': 'restructuredtext',
+ '.txt': 'markdown',
+ '.md': 'markdown',
+}
+
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3/', None),
+ 'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
diff --git a/docs/source/data/overview.md b/docs/source/data/overview.md
new file mode 100644
index 00000000..149ce871
--- /dev/null
+++ b/docs/source/data/overview.md
@@ -0,0 +1,3 @@
+# Data samples
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/dcomputing/overview.md b/docs/source/dcomputing/overview.md
new file mode 100644
index 00000000..aa7b3ecb
--- /dev/null
+++ b/docs/source/dcomputing/overview.md
@@ -0,0 +1,3 @@
+# Distributed Computing
+
+Under construction.
diff --git a/docs/source/development/overview.md b/docs/source/development/overview.md
new file mode 100644
index 00000000..dc7dd54c
--- /dev/null
+++ b/docs/source/development/overview.md
@@ -0,0 +1,3 @@
+# Development Process Overview
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/framework/overview.md b/docs/source/framework/overview.md
new file mode 100644
index 00000000..2f9ab156
--- /dev/null
+++ b/docs/source/framework/overview.md
@@ -0,0 +1,3 @@
+# Framework
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/generator/overview.md b/docs/source/generator/overview.md
new file mode 100644
index 00000000..5ca35b46
--- /dev/null
+++ b/docs/source/generator/overview.md
@@ -0,0 +1,3 @@
+# Physics Generator
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 00000000..03be042c
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,98 @@
+Welcome to CEPCSW Documentation
+===============================
+
+CEPCSW is built on top of Key4hep software stack.
+
+.. note::
+
+ This project is under active development.
+
+Contents
+--------
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Quickstart
+
+ quickstart/quickstart.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Development Process
+
+ development/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Framework
+
+ framework/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Generator
+
+ generator/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Simulation
+
+ simulation/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Tracking
+
+ tracking/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Calo
+
+ calo/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: PID
+
+ pid/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Analysis tools
+
+ analysis/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Data samples
+
+ data/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Distributed Computing
+
+ dcomputing/overview.md
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+ :caption: Release Notes
+
+ releasenotes/overview.md
+
+
+
diff --git a/docs/source/pid/overview.md b/docs/source/pid/overview.md
new file mode 100644
index 00000000..54ffb18b
--- /dev/null
+++ b/docs/source/pid/overview.md
@@ -0,0 +1,3 @@
+# PID
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/quickstart/quickstart.md b/docs/source/quickstart/quickstart.md
new file mode 100644
index 00000000..f720dd99
--- /dev/null
+++ b/docs/source/quickstart/quickstart.md
@@ -0,0 +1,10 @@
+# Quickstart
+
+## Setup at IHEP cluster
+
+CEPCSW is already deployed at IHEP CVMFS. You can use it as following:
+
+```bash
+$ source /cvmfs/cepcsw.ihep.ac.cn/prototype/releases/tdr24.3.1/setup.sh
+$ gaudirun.py $DETCRDROOT/scripts/CRD_o1_v01-SimRec.py
+```
diff --git a/docs/source/releasenotes/overview.md b/docs/source/releasenotes/overview.md
new file mode 100644
index 00000000..56dd792b
--- /dev/null
+++ b/docs/source/releasenotes/overview.md
@@ -0,0 +1,3 @@
+# Release Notes
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/simulation/overview.md b/docs/source/simulation/overview.md
new file mode 100644
index 00000000..1ba72965
--- /dev/null
+++ b/docs/source/simulation/overview.md
@@ -0,0 +1,3 @@
+# Simulation software
+
+Under construction.
\ No newline at end of file
diff --git a/docs/source/tracking/overview.md b/docs/source/tracking/overview.md
new file mode 100644
index 00000000..0ff0d39e
--- /dev/null
+++ b/docs/source/tracking/overview.md
@@ -0,0 +1,3 @@
+# Tracking
+
+Under construction.
\ No newline at end of file
--
GitLab