Description

Format documents

Generators of the Word documents that describe the BmnRoot data formats for physicists, and of the BmnRoot Start Guide. The same generators write the documents as Markdown pages: they are the Related Pages of the Doxygen documentation (http://nica.pages.jinr.ru/bmnroot/), generated by services/doxygen.

File	Content
docx_helpers.py	Common layout of the format documents: page and styles, tables, code blocks, title page, clickable table of contents
format_md.py	Markdown writer of the format documents with the functions of docx_helpers.py
doc_common.py	Data of the format documents shared by both writers: data volume tables, order of the rows by the availability
make_dst_doc.py	Content of the DST format document (BmnRoot_DST_Format.docx)
make_digi_doc.py	Content of the DIGI format document (BmnRoot_DIGI_Format.docx)
guide_helpers.py	Layout of the Start Guide: text, lists, code blocks, tables, figures, table of contents and chapter sections, added to the template of the guide
guide_md.py	Markdown writer of the Start Guide with the functions of guide_helpers.py
md_writer.py	Markdown page shared by format_md.py and guide_md.py: title, headings, tables, code blocks, text escaped for Doxygen
make_start_guide.py	Content of the BmnRoot Start Guide (BmnRoot_Start_Guide.docx)
start_guide/template.docx	Template of the Start Guide: styles, title page, headers and footers, list numbering
start_guide/figure<N>.png	Figures of the Start Guide
branch_sizes.C	Sizes of the branches per event, used for the data volume tables (Appendix E of the documents)
dst/read_dst_example.C	Example of reading a DST file directly (Section 9.3 of the DST document)
dst/BmnPtAnalysis.h	Example of an analysis task for run_ana_bmn.C (Section 9.2 of the DST document)
digi/read_digi_example.C	Example of reading a simulated or experimental DIGI file directly (Section 10.3 of the DIGI document)
digi/BmnGemDigitQa.h, digi/run_digi_task.C	Example of a FairRoot task for DIGI files and the macro running it (Section 10.2 of the DIGI document)
dst/branch_sizes_.txt, digi/branch_sizes_.txt	Output of branch_sizes.C for simulated and experimental files of the Run 9 setup

The example macros are inserted into the documents as they are, so a change of a macro changes the document after the next generation. Check the macros on both file types before regenerating, for example:

source <bmnroot build directory>/config.sh
cd services/format_docs/digi
root -b -q -l 'read_digi_example.C("bmnsim.root")'
root -b -q -l 'run_digi_task.C("bmn_run<run>_digi.root", "digi_qa.root")'

The DST document describes the DST format of the commit given on its title page. The examples in dst/ use the interface of BmnGlobalTrack of that version and have to be updated together with the document for later changes of the class.

Requirements

Python 3 with python-docx (pip install python-docx); the Markdown pages need Python 3 only
LibreOffice (soffice) and pdftotext (poppler-utils): the document is rendered once to put the page numbers into the table of contents, so that the contents are correct without updating the fields in Word

Generating the documents

python3 services/format_docs/make_dst_doc.py BmnRoot_DST_Format.docx
python3 services/format_docs/make_digi_doc.py BmnRoot_DIGI_Format.docx
python3 services/format_docs/make_start_guide.py BmnRoot_Start_Guide.docx

The scripts print the number of headings and the headings whose page was not found in the rendering (the list must be empty).

An output file with the .md extension gives the Markdown page of the document instead of the Word document, for example:

python3 services/format_docs/make_dst_doc.py BmnRoot_DST_Format.md

The page has the label of the document title (e.g. bmnroot_dst_format, the page bmnroot_dst_format.html of the documentation), the table of contents made by Doxygen, and the figures of the Start Guide found by Doxygen in IMAGE_PATH. The DoxygenDoc target generates the three pages, so a change of the generators gets into the published documentation automatically. A new function of docx_helpers.py or guide_helpers.py used by the documents has to be added to format_md.py or guide_md.py too.

Start Guide

The Start Guide keeps its own look, so it is not built on docx_helpers.py: guide_helpers.py opens start_guide/template.docx and adds the table of contents and the chapters to it. To change the text of the guide, edit make_start_guide.py and generate the document again. The guide is published at https://bmn.jinr.int/bmnroot_start_guide/.

Text markup: `name` – italics for the names of classes, functions, files and variables, **bold**, ``monospace`` , ^superscript^, [text](URL) – link. The space in "Section N" is made non-breaking.
para, bullets (a nested list is the second level), numbered (an item can be followed by its code block), definitions ("term – description", the term is shown in bold italics), acronyms, code, command (terminal commands with the $ prompt), table, figure – see the descriptions in guide_helpers.py.
h1("N. Title") starts a chapter: a new section with the chapter number and title in the page header. The headings of all three levels get into the table of contents.
figure(N, caption, width) inserts start_guide/figure<N>.png with the caption "Figure N. caption"; the references to the figures in the text are written by hand.
The date of the title page is the argument of title_page. The other text of the title page, the page size, the styles of the headings and of the contents, the headers and footers are changed in template.docx with Word: its last section is the pattern of a chapter section.

Updating the data volume tables

branch_sizes.C takes the size on disk of every branch from sizeOnDisk() of macro/profiling/size/calculate_size.C (baskets of the branch and its sub-branches plus the branch object, which holds the baskets kept in memory) and divides it by the number of events. Only the tree header is read, so the whole file is used even for large files.

source <bmnroot build directory>/config.sh
cd services/format_docs
root -b -q -l 'branch_sizes.C("bmndst_sim.root")' | grep -E '^(#|SIZE)' > dst/branch_sizes_sim.txt
root -b -q -l 'branch_sizes.C("bmndst_exp.root")' | grep -E '^(#|SIZE)' > dst/branch_sizes_exp.txt
root -b -q -l 'branch_sizes.C("bmnsim.root")' | grep -E '^(#|SIZE)' > digi/branch_sizes_sim.txt
root -b -q -l 'branch_sizes.C("bmn_run<run>_digi.root")' | grep -E '^(#|SIZE)' > digi/branch_sizes_exp.txt

Update the description of the setup in Appendix E of the generators if the files are taken from another setup or run period.

Directory dependency graph for format_docs:

Directories
	digi
	DIGI format document: examples
	dst
	DST format document: examples

Files
	branch_sizes.C