diff --git a/.build.ci.sh b/.build.ci.sh index 3710b9a60e58ff641bb95065c31ffc1b232cbc55..ccea1de532720e678c9fca8ecde86b3a088e266e 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 26bfdba73b515afbb73ceb0224d052c107768885..c56157326e5848ef5cf3df797addd0d5eae248a7 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 0000000000000000000000000000000000000000..9138a7fe53ac0aea15b9ad865dd4bfc0f5d6d1f2 --- /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 0000000000000000000000000000000000000000..6ab5cd7a5eb419557136e194b186a2d9ac26edb8 --- /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 0000000000000000000000000000000000000000..d0c3cbf1020d5c292abdedf27627c6abe25e2293 --- /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 0000000000000000000000000000000000000000..6247f7e231716482115f34084ac61030743e0715 --- /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 0000000000000000000000000000000000000000..953e51ece207d2338f62a7c4249236992cc178d9 --- /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 0000000000000000000000000000000000000000..21911da033ef591d0433c06fc6ac7010d50ac3ce --- /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 0000000000000000000000000000000000000000..b5781fb86239eb9a4454bb17366af5704e68b97f --- /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 0000000000000000000000000000000000000000..45bbfe118152a15cea506e4321a16c7b4b195e5e --- /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 0000000000000000000000000000000000000000..149ce8717abb982831b9f7ad2c98f3e75b4156b2 --- /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 0000000000000000000000000000000000000000..aa7b3ecb2c0866b876b014b56e6fc09af9f8a5d0 --- /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 0000000000000000000000000000000000000000..dc7dd54c98e71836492a9ecb211398227a5ce306 --- /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 0000000000000000000000000000000000000000..2f9ab156a7299e1984a459b2bab3a6ba2ebf477f --- /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 0000000000000000000000000000000000000000..5ca35b4633b1cff208ca953c98e99d5e4c92cd68 --- /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 0000000000000000000000000000000000000000..03be042cf75325fe0f691805825ce2db8dccf258 --- /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 0000000000000000000000000000000000000000..54ffb18b1f93bb29b8d84e553bfc0abca7d96a9f --- /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 0000000000000000000000000000000000000000..f720dd99d9114486f7ab552ecd4129120e12ccda --- /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 0000000000000000000000000000000000000000..56dd792b3e7ee50404b3d8a17ec40b5c2b4ed856 --- /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 0000000000000000000000000000000000000000..1ba729658d159f700b6440c7707220ab4f6ff313 --- /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 0000000000000000000000000000000000000000..0ff0d39e8cc8e641de99faecb949b62a3ba2034d --- /dev/null +++ b/docs/source/tracking/overview.md @@ -0,0 +1,3 @@ +# Tracking + +Under construction. \ No newline at end of file