EIC code displayed by LXR master/​jana2/​docs/​development/​documentation.md	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

Warning, /jana2/docs/development/documentation.md is written in an unsupported language. File is not indexed.

 # 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. 
 
 - The C++ reference part is generated by [Doxygen](https://www.doxygen.nl)
 - The main website is powered by [Docsify](https://docsify.js.org/)
 
 
 ## Docsify
 
 Docsify is an open-source tool for generating documentation websites directly from Markdown files. 
 It dynamically converts Markdown files into a website without the need for a build process.
 
 - Docsify uses GFM (Git Flawored Markdown) with additional features such as possibility to include one document in another
 - [Docsify markdown features](https://docsify.js.org/#/helpers?id=important-content)
 - [Full markdown typography used in JANA2 theme](https://jhildenbiddle.github.io/docsify-themeable/#/markdown)
 
 
 
 ### Running on local machine
 
 To preview the documentation on local machine, you can open `./docs` folder in any server application. 
 Here is a python one-liner that makes the site running at `localhost:3000`
 
 ```bash
 # assuming current working directoy is JANA2/docs 
 python3 -m http.server 3000
 ```
 
 > On windows machines you may have to use `python` instead of `python3`
 
 
 
 ### Adding content
 
 Any markdown file added to docs folder will be automatically rendered by docsify if correct link is given. 
 A file `text.md` is displayed by a link `<domain>#/text.md`
 
 E.g. a file:
 
 ``` 
 JANA2/docs/jana1to2/developers-transition-guide.md
 ```
 
 Is accessible as:
 
 ```
 # localhost (if run by server above): 
 http://localhost:3000/#/jana1to2/developers-transition-guide.md
 
 # GitHub pages when merged into master
 https://jeffersonlab.github.io/JANA2/#/jana1to2/developers-transition-guide.md
 ```
 
 ### Menus
 
 While new content may be seen right away, it is not automatically getting added to the side menu. 
 To add links no new pages to left side menu, one has to edit `_sidebar.md`, which is pretty self explanatory. 
 
 `_coverpage.md` is responsible for the cover page content (with gnomes as of 2024). 
 
 
 ### Writing documentation
 
 Here are couple recommendations to the documentation writing: 
 
 
 - Use subdirectories for a group of documents and topics. Such as `howto` or `jana1to2`
 - Use low case with dashes `low-case-with-dashes.md` file names style. It is considered to be better for search engine parsers. 
 - Put pictures into corresponding subfolder or if a picture has a global context, to docs/_media folder. Create _media subfolders as needed. 
 - Always follow the document purpose. Think if document falls into `How-to`, `Tutorial`,  `Explanation/documentation` or `Reference guide`. 
   Don't mix them together (even if sometimes adding a bit of theory in tutorial seems tempting - don't do it!)
   More about it in [the documentation theory here](https://docs.divio.com/documentation-system/)
 
 
 
 
 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)
 
 
 ## 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 -->
 ```
 

This page was automatically generated by the 2.3.7 LXR engine. The LXR team