C.1 Docs / Files#
[1] Docs#
A rivt doc is the output of a rivt file processed by rivtlib. Each rivt file outputs a formatted doc with a doc number derived from the rivt file name. The doc is written to the respective subfolder of the _published folder.
Each rivt file outputs a corresponding doc of the format specified in PUBLISH command of the rv.D() API. A rivt file number has the form:
rvAnn-filename.py
where rvAnn is a required file number prefix with A an alphanumeric character and nn a two digit non-negative integer. Corresponding rivt docs are output as:
rvAnn-filename.txt, pdf or html
A rivt report is organized using the file numbers. The file numbers are used to organize reports into divisions and subdivisions. Each rivt file or doc is a report subdivision. If the rivt filenames are:
rvA01-filename.py
rv105-filename.py
rv212-filename.py
the corresponding doc numbers in a report would be:
A.1 (division A, subdivision 1)
1.5 (division 1, subdivision 5)
2.12 (division 2, subdivision 12)
A rivt report is organized using rivt doc numbers
[2] 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
[3] 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