Skip to content

Adding mkdocs Documentation

Samuel Ross Meehan requested to merge add-mkdocs into master

This adds cleaning mkdocs-based documentation that is build in CI and deployed to https://faserdaq.web.cern.ch/faserdaq/. This documentation is a combination of two types of documentation :

[1] Manually Written : I have compiled many ToDo's along with my own knowledge of how to build and use the faser/daq setup. This is hardcoded in the documentation with links to the relevant source code.

[2] Autogenerated : There are two bits of the code that use mkdocs modules to retrieve and build supplementary documentation so that the docs here stay current with the latest state of faser/daq :

  • doxygen : All of the submodules on which the code relies are included via a build of their doxygen documentation. As such, developers of those code bases should strive to improve that documentation and it will get automatically picked up by this code during the next merge request to this repo. This should be fine because at latest, it will get picked up when there is a version bump of a submodule.
  • configuration schemas : The schemas for all of the FASER module types are automatically parsed to provide a comprehensive list/description of each of the configuration settings for that module. As such, developers should strive to keep the schemas verbosely updated so that their settings can get fully parsed. This module was written expressly for that purpose and is housed here - https://github.com/smeehan12/mkdocs-doxygen-plugin

In addition to the existing progress here, there are a few bits and pieces for which input from other individuals are needed to bring these to completion :

  • @engamber epdtdi-daq01 : What is this machine used for and how is it docs/setup.md? This is referenced in the setup directions as a possible machine for use, but why do we need it if we have faser-daq-001/002? Should we refrain from directing users to it?
  • @cantel Module Monitoring : In the section housed in docs/configuration.md, there is guidance on how to configure monitoring modules. I am not sure of what we should be guiding people to do. Should they really be configuring these modules? i.e. should the modules have anything other than connections?
  • @cantel Hardware layout for TLB : In the introduction housed in the index.md file, there are brief descriptions on each of the hardware systems and how it functions. This is meant to allow a newcomer to have an entrypoint so that it is not just a black box. You can find the extent of detail necessary for the digitizer. Can you add this for the TLB?
  • @otheiner @kschmied hardware layout for TRB : In the introduction housed in the introduction.md file, there are brief descriptions on each of the hardware systems and how it functions. This is meant to allow a newcomer to have an entrypoint so that it is not just a black box. You can find the extent of detail necessary for the digitizer. Can you add this for the TRB?
  • @cantel @egalanta Running histogram viewer application : In the docs/monitoring.md section, there are HowTo's for people that don't know how to use a various application. Can you add the directions for the section on the Histogram-Based monitoring?
  • @aagaard Storage in EOS : In the docs/outputdata.md file, there is a section near the end on data storage on EOS. I don't know if this is done.
  • @aagaard Basic analysis : In the docs/outputdata.md file, I was hoping that we could include directions on how to make the nice set of plots that visualize a single event. Are those scripts in faser/daq and can be documented here?
  • @aagaard @engamber Installation instructions : On the README_FASER, there seem to have some setup stuff that I didn’t know about (Cassandra and Flask(for GUI)) and I'm not sure of how/where this should be most appropriately folded into the main documentation

Feel free to comment on these questions below and I can fold them into the branch.

Licensing : This MR further includes the addition of a file that will scan the repo for the proper licensing of its content by including a Copyright where appropriate.

Edited by Samuel Ross Meehan

Merge request reports