Skip to content

Commit

Permalink
Merge pull request #334 from DraTeots/master
Browse files Browse the repository at this point in the history
Documentation re-design
  • Loading branch information
faustus123 authored Aug 8, 2024
2 parents 90e9cd8 + e0ce3b6 commit be8ab27
Show file tree
Hide file tree
Showing 57 changed files with 3,144 additions and 2,036 deletions.
78 changes: 78 additions & 0 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
@@ -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
3 changes: 1 addition & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,7 @@ Makefile
/plugins/

# Doxygen generated files
docs/html/*
docs/latex/*
/docs/doxygen_build/*

# IDE artifacts
*.swp
Expand Down
Empty file added docs/.nojekyll
Empty file.
41 changes: 0 additions & 41 deletions docs/.readthedocs.yaml

This file was deleted.

17 changes: 3 additions & 14 deletions docs/Contributing.md
Original file line number Diff line number Diff line change
@@ -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
=====================

Expand Down Expand Up @@ -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')
66 changes: 66 additions & 0 deletions docs/Documentation.md
Original file line number Diff line number Diff line change
@@ -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)
Loading

0 comments on commit be8ab27

Please sign in to comment.