Merge pull request #336 from DraTeots/master

Multiple minor fixes to the new documentation system

docs/Download.md

@@ -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)
 

docs/_coverpage.md

@@ -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)

docs/_sidebar.md

@@ -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')

docs/Contributing.md → docs/development/contributing.md

@@ -1,5 +1,5 @@
-Contributing to JANA2
-=====================
+Contributing
+============
 
 ## Coding Conventions
 
@@ -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')

docs/development/development.md

@@ -0,0 +1,7 @@
+# JANA2 for developers
+
+[filename](contributing.md ':include')
+
+[filename](documentation.md ':include')
+
+[filename](mermaid.md ':include')

docs/Documentation.md → docs/development/documentation.md

@@ -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, 
@@ -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/#/
 

docs/development/mermaid.md

@@ -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>
+

docs/doxygen/doxygen_footer.html

@@ -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);
   });

docs/doxygen/doxygen_index.md

@@ -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
 
 

docs/howto/group-events.md

@@ -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 

docs/howto/Howto.md → docs/howto/other-howtos.md

@@ -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

docs/howto/streaming.md

@@ -1,4 +1,4 @@
-# Stream data to and from JANA
+# Stream data to and from JANA <!-- {docsify-ignore-all} -->
 
 
 ## Messages and Events
@@ -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.
@@ -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();
@@ -55,7 +55,5 @@
 
     Message formats each get their own class, which must inherit from the JMessage and JEventMessage interfaces.
 
-4. 
-
 
 

docs/index.html

@@ -30,6 +30,10 @@
             --cover-blockquote-color: #f8c213;
             --cover-color: #e7e7e7;
         }
+
+        .cover-text {
+            color: var(--cover-color);
+        }
     </style>
 </head>
 

docs/index.md

@@ -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
@@ -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