From f5f0c2a1f2fae043c07d8cbf86af55b5e3c781ed Mon Sep 17 00:00:00 2001 From: Christopher Dilks Date: Mon, 20 Oct 2025 11:30:47 -0400 Subject: [PATCH 1/2] doc: setup guide, and cleanup main README.md --- README.md | 32 ++++++------------------- docs/mkdocs/docs/index.md | 1 + docs/mkdocs/docs/setup.md | 49 +++++++++++++++++++++++++++++++++++++++ docs/mkdocs/mkdocs.yaml | 3 ++- 4 files changed, 59 insertions(+), 26 deletions(-) create mode 100644 docs/mkdocs/docs/setup.md diff --git a/README.md b/README.md index d6ede64b61..41938c803b 100644 --- a/README.md +++ b/README.md @@ -3,30 +3,12 @@ [![Validation Status](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml/badge.svg)](https://github.com/JeffersonLab/coatjava/actions/workflows/validation.yml) [![Coverage](https://badgen.net/static/JaCoCo/coverage/purple)](https://jeffersonlab.github.io/coatjava/jacoco) -- [**Documentation Homepage**](https://jeffersonlab.github.io/coatjava) -- [API Documentation (Javadoc)](https://jeffersonlab.github.io/coatjava/javadoc) -- [Developer notes](/docs/dev_notes.md) +| Table of Contents | | +| --- | --- | +| [:star: **Documentation Homepage** :star:](https://jeffersonlab.github.io/coatjava) | API documentation, HIPO banks, and more | +| [Developer notes](/docs/dev_notes.md) | Notes for developers and maintainers | ----- +--- -The original repository for COATJAVA was named "clas12-offline-software" and is [now archived and read-only](https://github.com/JeffersonLab/clas12-offline-software). On May 17, 2023, this new repository was created by running BFG Repo Cleaner to get rid of old, large data files and things that should never have been in the repository, giving 10x reduction in repository size, clone time, etc, and renamed `coatjava`. The most critical, GitHub-specific aspects have been transferred to this new repository: - -* Open issues -* Branch protection rules -* User access permission - -But some things remain only in the original repository: - -* Release notes up to 9.0.1 (probably worth transferring) -* Closed issues (probably not worth transferring) -* Wiki (never really utilized and probably worth restarting from scratch) - -Due to the cleanup, previously existing forks and local copies of the old repository will not be automatically mergeable. - ----- - -If you just want to use the software without modifying/building it, you can download a pre-built package from the [GitHub releases](https://github.com/JeffersonLab/coatjava/releases) page or the corresponding repo at [JLab](https://clasweb.jlab.org/clas12offline/distribution/coatjava/). Builds on JLab machines are also available, see the [general software wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center) for setting up your environment to use them. - -For anything more, see the "General Developer Documentation" link on that software wiki, which points [here](https://clasweb.jlab.org/wiki/index.php/COATJAVA_Developer_Docs). - -The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated. +> [!NOTE] +> The original repository for COATJAVA was named "clas12-offline-software" and is [now archived and read-only](https://github.com/JeffersonLab/clas12-offline-software). On May 17, 2023, this new repository was created by running BFG Repo Cleaner to get rid of old, large data files and things that should never have been in the repository, giving 10x reduction in repository size, clone time, etc, and renamed `coatjava`. diff --git a/docs/mkdocs/docs/index.md b/docs/mkdocs/docs/index.md index ba2d31a68f..25a1cf9442 100644 --- a/docs/mkdocs/docs/index.md +++ b/docs/mkdocs/docs/index.md @@ -6,6 +6,7 @@ | --- | --- | | [**API Documentation**](javadoc/index.html) | Documentation for classes and methods | | [**HIPO Banks**](banks.md) | Bank descriptions | +| [**Setup and Installation**](setup.md) | How to obtain or build and install the software | | [**Source code**](https://github.com/JeffersonLab/coatjava) | The source code `git` repository | --- diff --git a/docs/mkdocs/docs/setup.md b/docs/mkdocs/docs/setup.md new file mode 100644 index 0000000000..b6a0d06749 --- /dev/null +++ b/docs/mkdocs/docs/setup.md @@ -0,0 +1,49 @@ +# Setup Guide + +
+## Obtaining the Software + +If you just want to use the software without modifying/building it, you can download a pre-built package from the [GitHub releases](https://github.com/JeffersonLab/coatjava/releases) page or the corresponding repo at [JLab](https://clasweb.jlab.org/clas12offline/distribution/coatjava/). Builds on JLab machines are also available, see the [general software wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center) for setting up your environment to use them. + +If you would rather build and install it yourself, `git clone` [the repository](https://github.com/JeffersonLab/coatjava), then skip to the next section below. + +For anything more, see the "General Developer Documentation" link on that software wiki, which points [here](https://clasweb.jlab.org/wiki/index.php/COATJAVA_Developer_Docs). + +The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated. + +
+## Dependencies + +- Java +- Maven + +Maven will automatically obtain all other dependencies. + +
+## Building and Installing + +Run the installation script: +``` +./build-coatjava.sh +``` + +For more usage guidance, run: +``` +./build-coatjava.sh --help +``` + +The software will then be installed _within_ the top-level repository directory, in a subdirectory named `coatjava/`, which contains: + +| Directory | Description | +| --- | --- | +| `bin` | Executables for the user, such as `recon-util` | +| `etc` | Various supplementary files, such as bank schema and magnetic field maps | +| `lib` | JAR files | +| `libexec` | Internal scripts | + +
+## Troubleshooting + +If you want to _cleanly_ rebuild, use the `--clean` option for `build-coatjava.sh`. + +If you need to clean your Maven cache, which by default is stored in `~/.m2/repository`, you can try either removing that directory, or renaming it, so that it is recreated. Then try to build `coatjava` again. diff --git a/docs/mkdocs/mkdocs.yaml b/docs/mkdocs/mkdocs.yaml index b6837d28b0..8e2fd29e16 100644 --- a/docs/mkdocs/mkdocs.yaml +++ b/docs/mkdocs/mkdocs.yaml @@ -1,7 +1,8 @@ site_name: COATJAVA Documentation nav: - Home: index.md - - HIPO Bank Definitions: banks.md + - HIPO Banks: banks.md + - Setup Guide: setup.md use_directory_urls: false extra: homepage: index.html From 8688d2a2ff41bb263cb534ea9132d902f4d25e0b Mon Sep 17 00:00:00 2001 From: Christopher Dilks Date: Mon, 20 Oct 2025 11:34:17 -0400 Subject: [PATCH 2/2] fix: linebreaks --- docs/mkdocs/docs/setup.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/mkdocs/docs/setup.md b/docs/mkdocs/docs/setup.md index b6a0d06749..254e603861 100644 --- a/docs/mkdocs/docs/setup.md +++ b/docs/mkdocs/docs/setup.md @@ -1,6 +1,7 @@ # Setup Guide
+ ## Obtaining the Software If you just want to use the software without modifying/building it, you can download a pre-built package from the [GitHub releases](https://github.com/JeffersonLab/coatjava/releases) page or the corresponding repo at [JLab](https://clasweb.jlab.org/clas12offline/distribution/coatjava/). Builds on JLab machines are also available, see the [general software wiki](https://clasweb.jlab.org/wiki/index.php/CLAS12_Software_Center) for setting up your environment to use them. @@ -12,6 +13,7 @@ For anything more, see the "General Developer Documentation" link on that softwa The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wiki/Troubleshooting) wiki page may also still be useful but likely outdated.
+ ## Dependencies - Java @@ -20,6 +22,7 @@ The [troubleshooting](https://github.com/JeffersonLab/clas12-offline-software/wi Maven will automatically obtain all other dependencies.
+ ## Building and Installing Run the installation script: @@ -42,6 +45,7 @@ The software will then be installed _within_ the top-level repository directory, | `libexec` | Internal scripts |
+ ## Troubleshooting If you want to _cleanly_ rebuild, use the `--clean` option for `build-coatjava.sh`.