Skip to content

Commit

Permalink
Merge pull request #336 from DraTeots/master
Browse files Browse the repository at this point in the history
Multiple minor fixes to the new documentation system
  • Loading branch information
faustus123 authored Aug 9, 2024
2 parents be8ab27 + 4faaec1 commit afa596e
Show file tree
Hide file tree
Showing 16 changed files with 117 additions and 179 deletions.
17 changes: 1 addition & 16 deletions docs/Download.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,4 @@
---
title: JANA: Multi-threaded HENP Event Reconstruction
---

<center>
<table border="0" width="100%" align="center">
<TH width="20%"><A href="index.html">Welcome</A></TH>
<TH width="20%"><A href="Tutorial.html">Tutorial</A></TH>
<TH width="20%"><A href="Howto.html">How-to guides</A></TH>
<TH width="20%"><A href="Explanation.html">Principles</A></TH>
<TH width="20%"><A href="Reference.html">Reference</A></TH>
</table>
</center>


## Get JANA
# Download

### Latest master (unstable)

Expand Down
52 changes: 0 additions & 52 deletions docs/Reference.md

This file was deleted.

11 changes: 6 additions & 5 deletions docs/_coverpage.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@


- <strong style="var(--cover-color)">Focus on scientific discovery!</strong> - JANA2 handles complex parallelization and scheduling,

- <strong class="cover-text">Focus on scientific discovery!</strong> - JANA2 handles complex parallelization and scheduling,
minimizing coding complexities (while still offering flexible tuning when needed)
- <strong style="var(--cover-color)">Scalability</strong> - High efficiency from personal computers to large-scale clusters.
- <strong style="var(--cover-color)">Modern C++ Core</strong> - Best industry practices, high-performance, low-risk code.
- <strong style="var(--cover-color)">Streaming readout</strong> - Handles both traditional event processing and streaming.
- <strong class="cover-text">Scalability</strong> - High efficiency from personal computers to large-scale clusters.
- <strong class="cover-text">Modern C++ Core</strong> - Best industry practices, high-performance, low-risk code.
- <strong class="cover-text">Streaming readout</strong> - Handles both traditional event processing and streaming.

<a href="https://github.com/JeffersonLab/JANA2/" target="_blank">GitHUB</a>
[Get Started](#docsify)
[Get Started](#JANA2)
12 changes: 5 additions & 7 deletions docs/_sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,8 @@
* [Monitoring](howto/monitor-debug-gui.md "JANA2: Status Debug Monitoring")
* [New experiments](howto/use-in-new-experiment.md "JANA2: How to use in new experiments")
* [Group Events](howto/group-events.md "JANA2: Group Events")
* [Streaming](howto/group-events.md "JANA2: Streaming readout")
* [Other HowTos](howto/howto.md "JANA2: HowTO list")
- Development
* [Contributing](Contributing.md)
* [Mermaid](mermaid-example.md)
* [C++ Reference](https://drateots.github.io/JANA2/refcpp/index.html ':target=_blank')
* [GitHub](https://github.com/JeffersonLab/JANA2 ':target=_blank')
* [Streaming](howto/streaming.md "JANA2: Streaming readout")
* [Other HowTos](howto/other-howtos.md "JANA2: HowTO list")
- [Development](development/development.md)
- [C++ Reference](https://drateots.github.io/JANA2/refcpp/index.html ':target=_blank')
- [GitHub](https://github.com/JeffersonLab/JANA2 ':target=_blank')
6 changes: 2 additions & 4 deletions docs/Contributing.md → docs/development/contributing.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
Contributing to JANA2
=====================
Contributing
============

## Coding Conventions

Expand Down Expand Up @@ -39,5 +39,3 @@ Add a line to `packages/jana2/package.py` that associates the release version wi
Note that the spack version identifier does _not_ have a 'v' prefix.


[filename](Documentation.md ':include')
[filename](mermaid-example.md ':include')
7 changes: 7 additions & 0 deletions docs/development/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# JANA2 for developers

[filename](contributing.md ':include')

[filename](documentation.md ':include')

[filename](mermaid.md ':include')
13 changes: 9 additions & 4 deletions docs/Documentation.md → docs/development/documentation.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
# Generating documentation
# Documentation

Generating documentation
The website documentation is automatically generated via GitHub Actions
[.github/workflows/documentation.yml](https://github.com/JeffersonLab/JANA2/blob/master/.github/workflows/documentation.yml)
and uploaded to GitHub Pages.

### Doxygen
- The main website is powered by [Docsify](https://docsify.js.org/)
- The C++ reference part is generated by [Doxygen](https://www.doxygen.nl)

## Doxygen

Doxygen is a widely used documentation generation tool for C++ projects.
It parses the source code and accompanying comments, formatted according to Doxygen's configurable markup,
Expand Down Expand Up @@ -52,7 +57,7 @@ Add this to doxygen footer before `</body>` closing tag:



### Docsify
## Docsify

The main documentation is powered by the Docsify JavaScript library https://docsify.js.org/#/

Expand Down
48 changes: 48 additions & 0 deletions docs/development/mermaid.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
## Mermaid diagrams

One way to use [Mermaid diagrams](https://mermaid.js.org) in the documentation:

<pre>
```mermaid
sequenceDiagram
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?
```
</pre>

```mermaid
sequenceDiagram
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?
```

The other one is by using `<pre class="mermaid">` HTML tags:

```html
<pre class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</pre>
```

<pre class="mermaid">
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
</pre>

2 changes: 1 addition & 1 deletion docs/doxygen/doxygen_footer.html
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
<script type="text/javascript">
$(document).ready(function() {
let navHeader = '<li><a href="https://github.com/JeffersonLab/JANA2" target="_blank">Project GitHUB</a></li>';
navHeader += '<li><a href="https://JeffersonLab.github.io/JANA2/#/" target="_blank">MAIN DOCUMENTATION</a></li>';
navHeader += '<li><a href="https://jeffersonlab.github.io/JANA2/#/README" target="_blank">MAIN DOCUMENTATION</a></li>';
// Append it to the navigation div or another appropriate place in the menu
$('#main-menu').append(navHeader);
});
Expand Down
36 changes: 18 additions & 18 deletions docs/doxygen/doxygen_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,35 +10,35 @@ This website provides documentation for JANA2 C++ API automatically generated by

## Main API

* [JApplication](http://www.jlab.org/JANA/jana_doc_latest/class_j_application.html): The main entry point into the program
* [JObject](http://www.jlab.org/JANA/jana_doc_latest/class_j_object.html): Data containers for specific results
* [JEventSource](http://www.jlab.org/JANA/jana_doc_latest/class_j_event_source.html): From a file or messaging producer, expose a stream of events. Each event is an aggregate of JObjects
* [JFactory](http://www.jlab.org/JANA/jana_doc_latest/class_j_factory.html): Given an event, calculate a specific result, potentially calling other JFactories recursively to obtain any prereqs
* [JEventProcessor](http://www.jlab.org/JANA/jana_doc_latest/class_j_event_processor.html): Run desired JFactories over the event stream, writing results to an output file or messaging consumer
* [JApplication](class_j_application.html): The main entry point into the program
* [JObject](class_j_object.html): Data containers for specific results
* [JEventSource](class_j_event_source.html): From a file or messaging producer, expose a stream of events. Each event is an aggregate of JObjects
* [JFactory](class_j_factory.html): Given an event, calculate a specific result, potentially calling other JFactories recursively to obtain any prereqs
* [JEventProcessor](class_j_event_processor.html): Run desired JFactories over the event stream, writing results to an output file or messaging consumer

## Streaming Extensions

* [JStreamingEventSource](http://www.jlab.org/JANA/jana_doc_latest/class_j_streaming_event_source.html): A starting point for structured, composable streaming
* [JTransport](http://www.jlab.org/JANA/jana_doc_latest/struct_j_transport.html): An interface for a generic messaging transport
* [JMessage](http://www.jlab.org/JANA/jana_doc_latest/struct_j_message.html): An interface for a stream buffer
* [JStreamingEventSource](class_j_streaming_event_source.html): A starting point for structured, composable streaming
* [JTransport](struct_j_transport.html): An interface for a generic messaging transport
* [JMessage](struct_j_message.html): An interface for a stream buffer

## User-facing utilities

* [JParameter](http://www.jlab.org/JANA/jana_doc_latest/class_j_parameter.html): Configure the behavior of components at runtime
* [JLogger](http://www.jlab.org/JANA/jana_doc_latest/struct_j_logger.html): Publish debugging information to standard out in a structured, convenient, threadsafe way
* [JService](http://www.jlab.org/JANA/jana_doc_latest/struct_j_service.html): Share external (stateful) services such as calibration constants and magnetic field maps
* [JCsvWriter](http://www.jlab.org/JANA/jana_doc_latest/class_j_csv_writer.html): Conveniently debug a JFactory by writing its generated JObjects to CSV
* [JParameter](class_j_parameter.html): Configure the behavior of components at runtime
* [JLogger](struct_j_logger.html): Publish debugging information to standard out in a structured, convenient, threadsafe way
* [JService](struct_j_service.html): Share external (stateful) services such as calibration constants and magnetic field maps
* [JCsvWriter](class_j_csv_writer.html): Conveniently debug a JFactory by writing its generated JObjects to CSV

## Internal services

* [JLoggingService](http://www.jlab.org/JANA/jana_doc_latest/class_j_logging_service.html): Furnish the user with a logger already configured for that particular component
* [JParameterManager](http://www.jlab.org/JANA/jana_doc_latest/class_j_parameter_manager.html): Furnish the user with parameters extracted from command line flags and configuration files
* [JLoggingService](class_j_logging_service.html): Furnish the user with a logger already configured for that particular component
* [JParameterManager](class_j_parameter_manager.html): Furnish the user with parameters extracted from command line flags and configuration files

## Parallelism engine

* [JProcessingController](http://www.jlab.org/JANA/jana_doc_latest/class_j_processing_controller.html): The interface which any parallelism engine must adhere to
* [JArrowProcessingController](http://www.jlab.org/JANA/jana_doc_latest/class_j_arrow_processing_controller.html): The entry point into the "Arrow" engine
* [JWorker](http://www.jlab.org/JANA/jana_doc_latest/class_j_worker.html): Contains the loop for each worker thread, along with startup/shutdown logic and encapsulated worker state.
* [JScheduler](http://www.jlab.org/JANA/jana_doc_latest/class_j_scheduler.html): Contains the logic for giving a worker a new assignment
* [JProcessingController](class_j_processing_controller.html): The interface which any parallelism engine must adhere to
* [JArrowProcessingController](class_j_arrow_processing_controller.html): The entry point into the "Arrow" engine
* [JWorker](class_j_worker.html): Contains the loop for each worker thread, along with startup/shutdown logic and encapsulated worker state.
* [JScheduler](class_j_scheduler.html): Contains the logic for giving a worker a new assignment


19 changes: 3 additions & 16 deletions docs/howto/group-events.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,6 @@
---
title: JANA: Multi-threaded HENP Event Reconstruction
---

<center>
<table border="0" width="100%" align="center">
<TH width="20%"><A href="index.html">Welcome</A></TH>
<TH width="20%"><A href="Tutorial.html">Tutorial</A></TH>
<TH width="20%"><A href="Howto.html">How-to guides</A></TH>
<TH width="20%"><A href="Explanation.html">Principles</A></TH>
<TH width="20%"><A href="Reference.html">Reference</A></TH>
</table>
</center>

How To...
=========

# Group events <!-- {docsify-ignore-all} -->

## Detect when a group of events has finished

Sometimes it is necessary to organize events into groups, process the events the usual way, but then notify
Expand Down
18 changes: 2 additions & 16 deletions docs/howto/Howto.md → docs/howto/other-howtos.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,5 @@
---
title: JANA: Multi-threaded HENP Event Reconstruction
---

<center>
<table border="0" width="100%" align="center">
<TH width="20%"><A href="index.html">Welcome</A></TH>
<TH width="20%"><A href="Tutorial.html">Tutorial</A></TH>
<TH width="20%"><A href="Howto.html">How-to guides</A></TH>
<TH width="20%"><A href="Explanation.html">Principles</A></TH>
<TH width="20%"><A href="Reference.html">Reference</A></TH>
</table>
</center>

How To...
=========
# Other HowTos

This section walks the user through specific steps for solving a real-world problem.

Table of contents
Expand Down
12 changes: 5 additions & 7 deletions docs/howto/streaming.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Stream data to and from JANA
# Stream data to and from JANA <!-- {docsify-ignore-all} -->


## Messages and Events
Expand All @@ -13,15 +13,15 @@

If events are large enough (>0.5MB), the cleanest thing to do is to
establish a one-to-one relationship between messages and events. JANA provides
[JStreamingEventSource](html/class_j_streaming_event_source.html)
[JStreamingEventSource](refcpp/class_j_streaming_event_source.html)
to make this convenient.

If events are very small, you probably want many events in one message. A corresponding helper class does not
exist yet, but would be a straightforward adaptation of the above.

If upstream doesn't do any event building (e.g. it is reading out ADC samples over a fixed time window) you
probably want to have JANA determine physically meaningful event boundaries, maybe even incorporating a software
L2 trigger. This is considerably more complicated, and is discussed in [the event building how-to](Howto.html)
L2 trigger. This is considerably more complicated, and is discussed in [the event building how-to](./other-howtos.md)
instead.

For the remainder of this how-to we assume that messages and events are one-to-one.
Expand All @@ -32,9 +32,9 @@
2. The second question to ask is: What transport should be used?

JANA makes it so that the message format and transport can be varied independently. The transport wrapper need only
implement the [JTransport](html/struct_j_transport.html) interface, which is essentially just:
implement the [JTransport](refcpp/struct_j_transport.html) interface, which is essentially just:

```c++
```cpp
enum class Result {SUCCESS, TRYAGAIN};

virtual void initialize();
Expand All @@ -55,7 +55,5 @@

Message formats each get their own class, which must inherit from the JMessage and JEventMessage interfaces.

4.



4 changes: 4 additions & 0 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,10 @@
--cover-blockquote-color: #f8c213;
--cover-color: #e7e7e7;
}

.cover-text {
color: var(--cover-color);
}
</style>
</head>

Expand Down
11 changes: 6 additions & 5 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@

# JANA: Multi-threaded HENP Event Reconstruction
# JANA2

### C++ Reconstruction framework in Nuclear and High Energy Physics

## Welcome to JANA!
## Welcome to JANA2!

JANA is a C++ framework for multi-threaded HENP (High Energy and Nuclear Physics) event reconstruction.
JANA2 is a C++ framework for multi-threaded HENP (High Energy and Nuclear Physics) event reconstruction.
It is very efficient at multi-threading with a design that makes it easy for less experienced programmers
to contribute pieces to the larger reconstruction project. The same JANA program can be used to easily
to contribute pieces to the larger reconstruction project. The same JANA2 program can be used to easily
do partial or full reconstruction, fully maximizing the available cores for the current job.

Its design strives to be extremely easy to setup when first getting started, yet have a depth of customization
Expand All @@ -26,7 +27,7 @@ for(auto t : tracks){

## History

[JANA](https://halldweb.jlab.org/DocDB/0011/001133/002/Multithreading_lawrence.pdf) (JLab ANAlysis framework)
[JANA](https://halldweb.jlab.org/DocDB/0011/001133/002/Multithreading_lawrence.pdf) (**J**Lab **ANA**lysis framework)
was one of the earliest implementations of a multi-threaded, event processing framework designed to run on commercial
CPU hardware. The framework, which was developed since 2005, has been used for many aspects of [the GlueX experiment](https://arxiv.org/abs/1911.11239)
at Jefferson Lab which was commissioned in 2016. In addition to the reconstruction of both
Expand Down
Loading

0 comments on commit afa596e

Please sign in to comment.