Merge pull request #334 from DraTeots/master

Documentation re-design

.github/workflows/documentation.yml

@@ -0,0 +1,78 @@
+name: Documentation generation
+
+on:
+  push:
+    branches:
+      - '*'
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs/doxygen
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+
+      - name: Build Doxygen
+        run: |
+          doxygen Doxyfile
+
+      - name: Upload Doxygen Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: doxygen-full
+          path: ./docs/doxygen/doxygen_build/
+
+      - name: Cleanup after Doxygen
+        run: |
+          mv ./doxygen_build/html ../refcpp
+          rm -rf ./doxygen_build
+
+      - name: Upload Website Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: website
+          path: ./docs
+
+  deploy:
+    #if: github.ref == 'refs/heads/main'
+    permissions:
+      id-token: write
+      contents: read
+      pages: write
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: website
+          path: ./dist/
+
+      - name: Introspect
+        run: |
+          echo "--- pwd"
+          pwd
+          echo "--- ls ./docs/"
+          ls -latrh ./dist
+          echo "--- ls ./dist/"
+          ls -latrh ./dist/
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: './dist'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -55,8 +55,7 @@ Makefile
 /plugins/
 
 # Doxygen generated files
-docs/html/*
-docs/latex/*
+/docs/doxygen_build/*
 
 # IDE artifacts
 *.swp

docs/Contributing.md

@@ -1,17 +1,3 @@
----
-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>
-
 Contributing to JANA2
 =====================
 
@@ -52,3 +38,6 @@ 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/Documentation.md

@@ -0,0 +1,66 @@
+# Generating documentation
+
+Generating documentation
+
+### 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, 
+producing documentation in various output formats such as HTML, XML, and LaTeX.
+
+```bash
+# Assuming cwd is JANA2/ - repository root folder
+cd docs
+doxygen Doxyfile
+```
+
+The command will generate documentation in `doxygen_build` folder so then:
+
+- The output is saved to `docs/doxygen_build`
+- html web site: `docs/doxygen_build/html`
+- xml: `docs/doxygen_build/xml`
+- latex: `docs/doxygen_build/latex`
+
+One can test the generated website: 
+
+```bash
+# assuming cwd is JANA2/docs 
+python3 -m http.server -d doxygen_build/html/ 8000
+```
+
+To add doxygen links and some other fine tuning of doxygen page look, 
+header and footer files were generated. If doxygen will ever change the template, 
+those probably has to be regenerated: 
+
+```
+doxygen -w html doxygen_header.html doxygen_footer.html doxygen_stylesheet.css
+```
+
+Add this to doxygen footer before `</body>` closing tag: 
+
+```html
+<!-- JANA2 custom footer addition -->
+<script type="text/javascript">
+  $(document).ready(function() {
+      let navHeader = '<li><a href="https://github.com/JeffersonLab/JANA2" target="_blank">Project GitHUB</a></li>';
+      // Append it to the navigation div or another appropriate place in the menu
+      $('#main-menu').append(navHeader);
+  });
+</script>
+<!-- END JANA2 custom footer addition -->
+```
+
+
+
+### Docsify
+
+The main documentation is powered by the Docsify JavaScript library https://docsify.js.org/#/
+
+[Available plugins](https://docsify-theme-github.vercel.app/#/awesome?id=plugins):
+
+- Example panels [github](https://github.com/VagnerDomingues/docsify-example-panels) [demo](https://vagnerdomingues.github.io/docsify-example-panels/#/)
+- Docsify Fontawesome [github](https://github.com/erickjx/docsify-fontawesome) [Fontawesome](https://fontawesome.com/)
+- Select documentation version [github](https://github.com/UliGall/docsify-versioned-plugin)
+- Docsify themebable [github](https://jhildenbiddle.github.io/docsify-themeable/#/)
+- Theme switcher [github](https://github.com/
+- Marked is used as markdown [Marked](https://github.com/markedjs/marked)