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