C.4 Reports#
[1t] Report compilation#
A typical workflow for writing reports is to start with a similar rivt folder and edit the rivt files and report script that produces the report.
A report is assembled from multiple docs organized by division and subdivsion numbers provided in the rivt file name. Each doc is a subdivision of a report. A rivt file number has the form:
rvAnn-filename.py
where rv is a required prefix, A is an alphanumeric character and nn are two digit non-negative integers. The prefix is used to organize reports into divisions and subdivisions.
Corresponding rivt docs are output as:
rvAnn-filename.txt
rvAnn-filename.pdf
rvAnn-filename.html
A rivt report is organized using the rivt file numbers. If the rivt file names are:
rvA01-filename.py
rv105-filename.py
rv212-filename.py
the corresponding doc numbers in the would be:
A.1 (division A, subdivision 1)
1.5 (division 1, subdivision 5)
2.12 (division 2, subdivision 12)
Note that leading zeroes are dropped in the formatted output.
[2t] rivt-report.py#
The Python report script includes settings that specify assembly parameters and override defaults. These include:
Docs to be included in the report
Division names
recompiling docs
report cover page and title
provides the option to either regenerate all docs or to assemble the report from previously generated docs. Most aspects of the report appearance are determined at when generating docs.
An example rivt-report.py script is shown below.
#! python
from rivtlib.rvreport import * # noqa: F403
""" generate a rivt report
Sample report generating and config file.
Run this Python file to generate a rivt report. The report generating file
must located in /publish/subfolder where subfolder is the doc type. The
report output file name is the report title. It is written to the same
folder as the report script. Duplicate report file names are incremented.
A flag determines whether the report is assembled from existing doc files
or whether docs are regenerated prior to assembly. If a rivt or doc file is
specified for inclusion and not found a warning is given but the report is
still assembled.
A rivt report is a compilation of rivt docs organized into divisions and
subdivisions. rivt doc numbers define the organization. Default titles for
subdivisions are generated by stripping the doc number from the file name
and replacing hyphens with spaces. The default titles may be overridden in
rv.M for each rivt file.
See src/styles/rivt.ini for additional settings
"""
# ==================================
# report type
# ==================================
rptype = "pdf" # report type [html; pdf; pdftex; text]
rvrun = False # regenerate docs [True; False]
# ==================================
# report cover settings
# ==================================
# cover pages are located in /src
rptitle = "Solar Canopy Calculations"
rpsubtitle = "Larkspur, Ca"
rpauthor = "rhh"
rpdate = "<datetime>"
rptoc = True # add table of contents, "" to omit
rpcover = "/publish/cover1.pdf" # cover page, "" to omit
# ==================================
# include docs
# ==================================
# include these divisions in report
divlist = [[dv01, "Codes and Loads"],
[dv02, "Frame"],
[dv03, "Foundation"]]
# include these docs in report
# doc label is for reference only, may be empty string
doclist = [[rv101,"Codes"],
[rv102,"Loads"],
[rv201,"Frame"],
[rv202,"Solar"],
[rv301,"Foundation"],
[rv302,"Walls"]]
genreport() # noqa: F405
[3t] conf.py#
The conf.py file contains configuration settings for rivt docs and reports. A typical conf.py file looks like this:
#! python
from rivtlib.rvconfig import * # noqa: F403
""" configuration settings for rivt docs and reports
This file is stored in /src/Tools. Settings for both HTML and PDF docs are
included anc cover:
- metadata
- formatting
"""
import sys
import os
from pathlib import Path
sys.path.append(str(Path(".").resolve()))
project = "rivt doc"
copyright = "2023 StructureLabs LLC"
author = "rholland"
release = "0.3.8a7"
#
# -- Options for HTML and PDF output --------------------------------------
#
extensions = [
"sphinx.ext.githubpages",
"sphinx_togglebutton",
"sphinxcontrib.jquery",
"sphinx_copybutton",
"sphinx_favicon",
"sphinx.ext.duration",
"sphinx.ext.doctest",
"sphinx.ext.autodoc",
"sphinx_design",
"sphinx_new_tab_link",
"rst2pdf.pdfbuilder",
]
root_doc = "index"
duration_write_json = ""
html_show_sourcelink = False
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
source_suffix = [".rst", ".md"]
templates_path = ["_templates"]
locale_dirs = ["_locale"]
html_title = "rivt"
html_theme = "pydata_sphinx_theme"
html_context = {"default_mode": "dark"}
html_sidebars = {"**": ["sidebar-nav-bs.html"]}
html_static_path = ["_static", "_static/img"]
html_css_files = ["css/custom.css"]
html_theme_options = {
"pygments_light_style": "tango",
"pygments_dark_style": "github-dark",
"navbar_start": ["navbar-logo"],
"collapse_navigation": True,
"header_links_before_dropdown": 6,
"navbar_align": "left",
"show_toc_level": 1,
"navigation_depth": 1,
"footer_start": ["copyright"],
"footer_end": [],
"logo": {
"text": "rivt",
"image_dark": "rivhome11c.png",
"image_light": "rivhome11c.png",
},
}
favicons = [
{
"rel": "icon",
"sizes": "16x16",
"href": "favicon-16x16.png",
},
{
"rel": "icon",
"sizes": "32x32",
"href": "favicon-32x32.png",
},
]
#
# -- Options for PDF output -----------------------------------------------
#
# source start file, target name, title, author, options
# options: ('index', 'MyProject', 'My Project', 'Author Name', {'pdf_compressed': True})
# More than one author : \\r'Guido van Rossum\\Fred L. Drake, Jr., editor'
pdf_documents = [("rv001-single-doc", "rv001-single-doc", "rivt", "r holland")]
# Label to use as a prefix for the subtitle on the cover page
subtitle_prefix = "User Manual"
# A list of folders to search for stylesheets. Example:
pdf_style_path = ["./rstdocs/_static/pdfstyle"]
# A colon-separated list of folders to search for fonts. Example:
pdf_font_path = ["./rstdocs/_staticfonts"]
# A comma-separated list of custom stylesheets. Example:
pdf_stylesheets = ["./rstdocs/_static/pdfstyle/stylepdf1.yaml"]
# Example: compressed=True
pdf_compressed = False
# Language to be used for hyphenation support
pdf_language = "en_US"
# literal blocks wider than the frame overflow, shrink or truncate
pdf_fit_mode = "shrink"
# 1 means top-level sections start in a new page 0 disabled
pdf_break_level = 0
# When a section starts in a new page, force it to be 'even', 'odd',
# or just use 'any'
pdf_breakside = "any"
# If false, no coverpage is generated.
pdf_use_coverpage = True
# Name of the cover page template to use
pdf_cover_template = "pdfcover.rst"
# Page template name for "regular" pages
# pdf_page_template = 'cutePage'
# Documents to append as an appendix to all manuals.
# pdf_appendices = []
# Enable experimental feature to split table cells. Use it
# if you get "DelayedTable too big" errors
# pdf_splittables = False
# Set the default DPI for images
# pdf_default_dpi = 72
# Enable rst2pdf extension modules
# pdf_extensions = []
# Show Table Of Contents at the beginning?
pdf_use_toc = True
# How many levels deep should the table of contents be?
pdf_toc_depth = 9999
# Insert footnotes where they are defined instead of
# at the end.
pdf_inline_footnotes = True
# verbosity level. 0 1 or 2
# pdf_verbosity = 0
# If false, no index is generated.
pdf_use_index = True
# If false, no modindex is generated.
pdf_use_modindex = False
# Add section number to section references
pdf_use_numbered_links = False
# Background images fitting mode
pdf_fit_background_mode = "scale"
# Repeat table header on tables that cross a page boundary?
pdf_repeat_table_rows = True
# Enable smart quotes (1, 2 or 3) or disable by setting to 0
pdf_smartquotes = 0