From ef6a9583a07542ab196584f6b9cbc47c9009833f Mon Sep 17 00:00:00 2001 From: Dmitry Romanov Date: Thu, 8 Aug 2024 23:15:32 +0000 Subject: [PATCH 1/2] [docs] Fix cover page and index problems (#335) --- docs/_coverpage.md | 11 ++++++----- docs/index.html | 4 ++++ docs/index.md | 11 ++++++----- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/_coverpage.md b/docs/_coverpage.md index f0886ca62..1d835785a 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -6,11 +6,12 @@ -- Focus on scientific discovery! - JANA2 handles complex parallelization and scheduling, + +- Focus on scientific discovery! - JANA2 handles complex parallelization and scheduling, minimizing coding complexities (while still offering flexible tuning when needed) -- Scalability - High efficiency from personal computers to large-scale clusters. -- Modern C++ Core - Best industry practices, high-performance, low-risk code. -- Streaming readout - Handles both traditional event processing and streaming. +- Scalability - High efficiency from personal computers to large-scale clusters. +- Modern C++ Core - Best industry practices, high-performance, low-risk code. +- Streaming readout - Handles both traditional event processing and streaming. GitHUB -[Get Started](#docsify) \ No newline at end of file +[Get Started](#JANA2) \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index de2b0d12b..893b13231 100644 --- a/docs/index.html +++ b/docs/index.html @@ -30,6 +30,10 @@ --cover-blockquote-color: #f8c213; --cover-color: #e7e7e7; } + + .cover-text { + color: var(--cover-color); + } diff --git a/docs/index.md b/docs/index.md index b73ee7ef7..f5fe1f1f9 100644 --- a/docs/index.md +++ b/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 From 4faaec10b6514295aedfb6328e27e8335e731077 Mon Sep 17 00:00:00 2001 From: Dmitry Romanov Date: Thu, 8 Aug 2024 22:45:38 -0400 Subject: [PATCH 2/2] [doc] #335 - multiple fixes to new documentation system --- docs/Download.md | 17 +----- docs/Reference.md | 52 ------------------- docs/_sidebar.md | 12 ++--- .../contributing.md} | 6 +-- docs/development/development.md | 7 +++ .../documentation.md} | 13 +++-- docs/development/mermaid.md | 48 +++++++++++++++++ docs/doxygen/doxygen_footer.html | 2 +- docs/doxygen/doxygen_index.md | 36 ++++++------- docs/howto/group-events.md | 19 ++----- docs/howto/{Howto.md => other-howtos.md} | 18 +------ docs/howto/streaming.md | 12 ++--- docs/mermaid-example.md | 28 ---------- 13 files changed, 101 insertions(+), 169 deletions(-) delete mode 100644 docs/Reference.md rename docs/{Contributing.md => development/contributing.md} (94%) create mode 100644 docs/development/development.md rename docs/{Documentation.md => development/documentation.md} (84%) create mode 100644 docs/development/mermaid.md rename docs/howto/{Howto.md => other-howtos.md} (96%) delete mode 100644 docs/mermaid-example.md diff --git a/docs/Download.md b/docs/Download.md index e74fe2c43..8bcf47ef0 100644 --- a/docs/Download.md +++ b/docs/Download.md @@ -1,19 +1,4 @@ ---- -title: JANA: Multi-threaded HENP Event Reconstruction ---- - -
- - - - - - -
WelcomeTutorialHow-to guidesPrinciplesReference
-
- - -## Get JANA +# Download ### Latest master (unstable) diff --git a/docs/Reference.md b/docs/Reference.md deleted file mode 100644 index f3131440d..000000000 --- a/docs/Reference.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: JANA: Multi-threaded HENP Event Reconstruction ---- - -
- - - - - - -
WelcomeTutorialHow-to guidesPrinciplesReference
-
- -Reference -========= -This section describes the underlying machinery of JANA. This is essentially a launchpad into Doxygen. - -## 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 - -## 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 - -## 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 - -## 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 - -## 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 - - diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 8b50a4d88..435fbc4a2 100644 --- 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 b/docs/development/contributing.md similarity index 94% rename from docs/Contributing.md rename to docs/development/contributing.md index a45f1272b..8d697bc5b 100644 --- a/docs/Contributing.md +++ b/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') \ No newline at end of file diff --git a/docs/development/development.md b/docs/development/development.md new file mode 100644 index 000000000..4056c17d1 --- /dev/null +++ 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 b/docs/development/documentation.md similarity index 84% rename from docs/Documentation.md rename to docs/development/documentation.md index f6b5c4025..8ba884b7f 100644 --- a/docs/Documentation.md +++ b/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 `` 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 new file mode 100644 index 000000000..695130bb9 --- /dev/null +++ b/docs/development/mermaid.md @@ -0,0 +1,48 @@ +## Mermaid diagrams + +One way to use [Mermaid diagrams](https://mermaid.js.org) in the documentation: + +
+```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
long time, so long
that the text does
not fit on a row.
+
+    Bob-->Alice: Checking with John...
+    Alice->John: Yes... John, how are you?
+```
+
+ +```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
long time, so long
that the text does
not fit on a row. + + Bob-->Alice: Checking with John... + Alice->John: Yes... John, how are you? +``` + +The other one is by using `
` HTML tags: 
+
+```html
+
+    graph LR
+    A --- B
+    B-->C[fa:fa-ban forbidden]
+    B-->D(fa:fa-spinner);
+

+```
+
+
+    graph LR
+    A --- B
+    B-->C[fa:fa-ban forbidden]
+    B-->D(fa:fa-spinner);
+

+
diff --git a/docs/doxygen/doxygen_footer.html b/docs/doxygen/doxygen_footer.html
index 7a19d2aa2..b4a2b981e 100644
--- a/docs/doxygen/doxygen_footer.html
+++ b/docs/doxygen/doxygen_footer.html
@@ -22,7 +22,7 @@