[doc] #335 - multiple fixes to new documentation system

JeffersonLab · Aug 9, 2024 · 4faaec1 · 4faaec1
1 parent ef6a958
commit 4faaec1
Show file tree

Hide file tree

Showing 13 changed files with 101 additions and 169 deletions.
diff --git a/docs/Download.md b/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)
 

diff --git a/docs/Reference.md b/docs/Reference.md
diff --git a/docs/_sidebar.md b/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')
diff --git a/docs/Contributing.md → docs/development/contributing.md b/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')
diff --git a/docs/development/development.md b/docs/development/development.md
@@ -0,0 +1,7 @@
+# JANA2 for developers
+
+[filename](contributing.md ':include')
+
+[filename](documentation.md ':include')
+
+[filename](mermaid.md ':include')
diff --git a/docs/Documentation.md → docs/development/documentation.md b/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/#/
 

diff --git a/docs/development/mermaid.md b/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>
+
diff --git a/docs/doxygen/doxygen_footer.html b/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);
  });

diff --git a/docs/doxygen/doxygen_index.md b/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
 
 
diff --git a/docs/howto/group-events.md b/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 

diff --git a/docs/howto/Howto.md → docs/howto/other-howtos.md b/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

diff --git a/docs/howto/streaming.md b/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. 
-
 
 
diff --git a/docs/mermaid-example.md b/docs/mermaid-example.md