Skip to content

Commit b9e0658

Browse files
tomeichlersmithtomeichlersmith
authored
doc updates for website and image specification (#112)
* refactor and link patching using lychee * update links in central README * add lychee link checking * download pre-builds to save time when building * don't run CI if install-mdbook changes * remove old remote build of Geant4 I don't think it is helpful and if someone wants to mess with different Geant4 versions, I think they should be able to build it themselves or know how to build the image themself. * update runtime configuration, focusing on denv move deduction of image version to its own page * update package list from new Dockerfile * update badges and their links * finish transition of custom geant4 to denv+just * transition parallel containers to denv+just * rewording edit of contributing * reword and move the docs * draft an Acts page * subsection on pulling by digest * remove packages that have been pruned * store awk script with docs for anyone interested in updating the docs * link to srm-ifce * update PR and issue templates
1 parent a298adf commit b9e0658

25 files changed

Lines changed: 527 additions & 453 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,28 @@ assignees: ''
88
---
99

1010
**Describe the bug**
11-
A clear and concise description of what the bug is.
11+
<!-- A clear and concise description of what the bug is. -->
1212

1313
**To Reproduce**
14+
<!--
1415
Steps to reproduce the behavior:
1516
1. Go to '...'
1617
2. Click on '....'
1718
3. Scroll down to '....'
1819
4. See error
20+
-->
1921

2022
**Expected behavior**
21-
A clear and concise description of what you expected to happen.
23+
<!-- A clear and concise description of what you expected to happen. -->
2224

2325
**Screenshots**
24-
If applicable, add screenshots to help explain your problem.
26+
<!-- If applicable, add screenshots to help explain your problem. -->
2527

26-
**What tag of the container are you using?**
28+
**Image Details**
29+
Output of `denv config print`:
2730

28-
**What application are you using to run the container?**
31+
Specify Image Version:
32+
<!-- https://ldmx-software.github.io/dev-build-context/image-version.html has instructions on how to do this -->
2933

3034
**Additional context**
31-
Add any other context about the problem here.
35+
<!-- Add any other context about the problem here. -->

‎.github/ISSUE_TEMPLATE/package_request.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,18 @@ assignees: ''
88
---
99

1010
## Is your request related to a problem? Please describe.
11-
A clear and concise description of what the problem is. Ex. I'm used to using this package when [...]
11+
<!-- A clear and concise description of what the problem is. Ex. I'm used to using this package when... -->
1212

1313
## Describe the solution you'd like. What packages do you want installed?
14-
A clear and concise description of what you want to happen.
14+
<!-- A clear and concise description of what you want to happen. -->
1515

16-
**The Development Container is based on Ubuntu 22.04. How do you install your necessary packages on Ubuntu?**
16+
**The Development Image is based on Ubuntu 24.04. How do you install your necessary packages on Ubuntu?**
17+
<!--
1718
A description and list of commands to run, for example
1819
```
1920
apt-get install my-package
2021
```
22+
-->
2123

2224
**Additional context**
23-
Add any other context or screenshots about the feature request here.
25+
<!-- Add any other context or screenshots about the feature request here. -->

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 16 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,31 @@
11

22
I am adding a new package to the container, here are the details.
33

4-
### What new packages does this PR add to the development container?
4+
### What new packages does this PR add to the development image?
55
- package1
66
- package2
77

88
## Check List
99
- [ ] I successfully built the container using docker
10-
```
11-
# outline of container build instructions
12-
cd docker
10+
<!--
11+
cd dev-build-context
1312
git checkout my-updates
1413
docker build . -t ldmx/local:temp-tag
15-
```
14+
-->
1615
- [ ] I was able to build ldmx-sw using this new container build
17-
```
16+
<!--
1817
# outline of build instructions
19-
ldmx-container-pull local temp-tag
2018
cd ldmx-sw
21-
mkdir build
22-
cd build
23-
ldmx cmake ..
24-
ldmx make install
25-
```
19+
just use ldmx/local:temp-tag
20+
just configure
21+
just build
22+
-->
2623
- [ ] I was able to test run a small simulation and reconstruction inside this container
27-
```
24+
<!--
2825
# outline of test instructions
29-
cd $LDMX_BASE/ldmx-sw/build
30-
ldmx ctest
31-
cd ..
32-
for c in `ls ldmx-sw/*/test/*.py`; ldmx fire $c; done
33-
```
34-
- [ ] I was able to successfully use the new packages. Explain what you did to test them below:
35-
26+
cd ldmx-sw/build
27+
denv ctest
28+
denv LDMX_NUM_EVENTS=10 LDMX_RUN_NUMBER=1 fire ../.github/validation_samples/inclusive/config.py
29+
-->
30+
- [ ] I was able to successfully use the new packages.
31+
<!-- Explain what you did to test them below. -->

‎.github/install-mdbook‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
#!/bin/sh
2+
3+
set -o errexit
4+
set -o nounset
5+
6+
# Assume the environment variables MDBOOK_VERSION and MDBOOK_ADMONISH_VERSION are set
7+
8+
# Download a tar ball and then unpack it into a destination
9+
# Arguments
10+
# 1 - URL for the .tar.gz to download
11+
# 2 - target directory to unpack into
12+
download() {
13+
wget -q -O - "${1}" | tar -xz --directory "${2}"
14+
}
15+
16+
help() {
17+
cat <<\HELP
18+
19+
USAGE:
20+
./.github/install-mdbook [target]
21+
22+
ARGUMENTS:
23+
target : directory to download mdbook and mdbook-admonish into
24+
25+
ENVIRONMENT:
26+
We assume that MDBOOK_VERSION and MDBOOK_ADMONISH_VERSION are set
27+
to the desired versions like how it is done in the CI workflow.
28+
29+
HELP
30+
}
31+
32+
target="${HOME}/.local/bin"
33+
while [ "${#}" -gt 0 ]; do
34+
case "${1}" in
35+
-h|--help)
36+
help
37+
exit 0
38+
;;
39+
*)
40+
target="${1}"
41+
;;
42+
esac
43+
shift
44+
done
45+
46+
mkdir -p "${target}"
47+
download \
48+
https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
49+
"${target}"
50+
download \
51+
https://github.com/tommilligan/mdbook-admonish/releases/download/v${MDBOOK_ADMONISH_VERSION}/mdbook-admonish-v${MDBOOK_ADMONISH_VERSION}-x86_64-unknown-linux-gnu.tar.gz \
52+
"${target}"

‎.github/workflows/README.md‎

Lines changed: 0 additions & 45 deletions
This file was deleted.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ on:
1212
- '.github/workflows/mdbook.yml'
1313
- '.github/workflows/ldmx-sw-dependabot.yml'
1414
- '.github/workflows/README.md'
15+
- '.github/install-mdbook'
1516
branches:
1617
- "**"
1718
tags:

‎.github/workflows/mdbook.yml‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,17 +35,19 @@ jobs:
3535
steps:
3636
- uses: actions/checkout@v4
3737
- name: Install mdBook
38-
run: |
39-
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh
40-
rustup update
41-
cargo install --version ${MDBOOK_VERSION} --locked mdbook
42-
cargo install --version ${MDBOOK_ADMONISH_VERSION} --locked mdbook-admonish
38+
run: ./.github/install-mdbook
4339
- name: Setup Pages
4440
id: pages
4541
uses: actions/configure-pages@v5
4642
- name: Build with mdBook
4743
run: mdbook build
4844
working-directory: docs
45+
- name: Check Links
46+
id: lychee
47+
uses: lycheeverse/lychee-action@v2
48+
with:
49+
fail: true
50+
args: ./docs/book
4951
- name: Upload artifact
5052
uses: actions/upload-pages-artifact@v3
5153
with:

‎README.md‎

Lines changed: 38 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,62 @@
1+
<!--
2+
DEVELOPER NOTICE
3+
4+
Since this file is not in docs/src but we still copy it there for creating the website,
5+
we need to have all links in this file be the full link to the website so that the
6+
website works properly.
7+
8+
Instead of
9+
[my link](docs/src/page.md)
10+
Do
11+
[my link](https://ldmx-software.github.io/dev-build-context/page.html)
12+
-->
13+
114
# Development Image Build Context
215
The build context for the `ldmx/dev` images used for developing and running ldmx-sw.
316

417
<p align="center">
518
<a href="http://perso.crans.org/besson/LICENSE.html" alt="GPLv3 license">
619
<img src="https://img.shields.io/badge/License-GPLv3-blue.svg" />
720
</a>
8-
<a href="https://github.com/LDMX-Software/dev-build-context/actions" alt="Actions">
9-
<img src="https://github.com/LDMX-Software/dev-build-context/workflows/CI/badge.svg" />
21+
<a href="https://github.com/LDMX-Software/dev-build-context/actions/workflows/ci.yml" alt="Actions">
22+
<img src="https://github.com/LDMX-Software/dev-build-context/actions/workflows/ci.yml/badge.svg" />
1023
</a>
1124
<a href="https://hub.docker.com/r/ldmx/dev" alt="DockerHub">
12-
<img src="https://img.shields.io/github/v/release/LDMX-Software/docker" />
25+
<img src="https://img.shields.io/github/v/release/LDMX-Software/dev-build-context" />
1326
</a>
1427
</p>
1528

16-
There is a corresponding workflow in [ldmx-sw](https://github.com/LDMX-Software/ldmx-sw) that generates a [production docker container](https://hub.docker.com/repository/docker/ldmx/pro) using the container generated by this build context as a base image.
17-
This production container already has ldmx-sw built and installed on it and assumes the user wants to run the application.
18-
19-
### Use in ldmx-sw
29+
There is a corresponding workflow in [ldmx-sw](https://github.com/LDMX-Software/ldmx-sw) that generates a [production image](https://hub.docker.com/r/ldmx/pro) using the image generated by this build context as a base image.
30+
This production image already has ldmx-sw built and installed on it and assumes the user wants to run the application.
2031

21-
In _ldmx-sw_, an [environment script](https://github.com/LDMX-Software/ldmx-sw/blob/master/scripts/ldmx-env.sh) is defined in `bash` to setup the environment for both `docker` and `singularity` correctly.
22-
A description of this setup process is given for both [docker](docs/use_with_docker.md) and [singularity](docs/use_with_singularity.md) if you desire more information.
32+
## Usage
33+
The image is designed to be used with [`denv`](https://tomeichlersmith.github.io/denv/)
34+
which provides support for Docker, Podman, and Apptainer.
2335

24-
## Current Container Configuration
36+
## Software in Image
2537

2638
Software Package | Version | Construction Process
2739
---|---|---
28-
[Ubuntu Server](https://ubuntu.com/) | 22.04 | Base Image
29-
[Python](https://www.python.org/) | 3.10.6 | From Ubuntu Repos
30-
[cmake](https://cmake.org/) | 3.22.1 | From Ubuntu Repos
31-
[Boost](https://www.boost.org/doc/libs/1_74_0/) | 1.74.0 | From Ubuntu Repos
32-
[XercesC](http://xerces.apache.org/xerces-c/) | 3.2.4 | Built from source
33-
[Pythia6](https://pythia.org/pythia6/) | 6.428 | Built from source
34-
[ROOT](https://root.cern.ch/) | 6.22/08 | Built from source
35-
[Geant4](https://geant4.web.cern.ch/node/1) | [LDMX.10.2.3\_v0.5](https://github.com/LDMX-Software/geant4/tree/LDMX.10.2.3_v0.5) | Built from source
40+
[Ubuntu Server](https://ubuntu.com/) | 24.04 | Base Image
41+
[Python](https://www.python.org/) | 3.12.3 | From Ubuntu Repos
42+
[cmake](https://cmake.org/) | 3.28.3 | From Ubuntu Repos
43+
[Boost](https://www.boost.org/doc/libs/1_74_0/) | 1.83.0 | From Ubuntu Repos
44+
[XercesC](http://xerces.apache.org/xerces-c/) | 3.3.0 | Built from source
45+
[LHAPDF](https://www.lhapdf.org/) | 6.5.5 | Built from source
46+
[Pythia8](https://pythia.org/) | 8.313 | Built from source
47+
[ROOT](https://root.cern.ch/) | 6.34.04 | Built from source
48+
[Geant4](https://geant4.web.cern.ch/) | [LDMX.10.2.3\_v0.6](https://github.com/LDMX-Software/geant4/tree/LDMX.10.2.3_v0.6) | Built from source
3649
[Eigen](https://eigen.tuxfamily.org/index.php?title=Main_Page) | 3.4.0 | Built from source
37-
[LHAPDF](https://lhapdf.hepforge.org/) | 6.5.3 | Built from source
38-
[GENIE](http://www.genie-mc.org/) | 3.02.00 | Built from source
50+
[HEPMC3](https://hepmc.web.cern.ch) | 3.3.0 | Built from source
51+
[GENIE](http://www.genie-mc.org/) Generator | [3.02.02-ldmx](https://github.com/wesketchum/Generator/releases/tag/R-3_04_02-ldmx) | Built from source
52+
[GENIE](http://www.genie-mc.org/) Reweight | 1.04.00 | Built from Source
3953
[Catch2](https://github.com/catchorg/Catch2) | 3.3.1 | Built from source
4054
[ONNX Runtime](https://github.com/microsoft/onnxruntime) | 1.15.0 | Download pre-built binaries
4155

42-
A detailed list of all packages installed from ubuntu repositories is given [here](docs/ubuntu-packages.md),
43-
and documentation on the workflow and runner used to build the image is [here](docs/runner.md).
56+
A detailed list of all packages installed from ubuntu repositories is given
57+
[here](https://ldmx-software.github.io/dev-build-context/ubuntu-packages.html),
58+
and documentation on the workflow and runner used to build the image is
59+
[here](https://ldmx-software.github.io/dev-build-context/runner.html).
4460

4561
### Python Packages for Analyses
4662
Installed in Python 3.

‎ci/interop/README.md‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎ci/interop/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../docs/src/interop.md

0 commit comments

Comments
 (0)