C.1 | Publish#
[1] Docs#
rivt Doc Processing
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)
[4] Files / Folders#
rivt folders
| A rivt file is a Python file file that imports the
rivt file | rivtlib Python package and compiles to a text,
| PDF or HTML doc.
| A rivt project folder contains setting and
rivt project folder | configuration files for the IDE and version control,
| as well as one or more rvbook or rvreport folders.
| A rivtbook folder is a collection of rivt files with
rvbook folder | common subject matter organized to simplify selection
| selection of files and resources for inclusion in rivt
| A rivt report folder is a collection of rivt files
rvreport folder | organized for publication of rivt docs and reports
| as text, html or PDF files.
[2] Public files#
A feature of rivt is efficient control over public sharing of all or parts of a rivt file. Public rivt files are generated by rivtlib on a section by section basis defined by the API header substring. Each API function defines a section and has a public/private setting in the header. Sections are private by default (see :doc: <rvF01-quickref>).
rv._("""Section Label | doc;stored, private;public, section;merge
Content substring indented 4 spaces
...
""")
Sections are written to a rivt file in the /public folder with a file name composed as:
rivt file name
rvAnn-filename.py
modified with an additional hyphen
rv-Ann-filename.py
The public folder may be uploaded to a GitHub repo for public sharing. When files are downloaded for reuse the extra hyphens may be removed with a batch remove command (e.g. in VSCode).
2. Contribute to rivt and rivtlib
rivtlib can be improved by:
providing pull requests.
submitting issues and bugs.
contributing to documentation and examples.
rivt can be improved by:
contributing to packages and extensions used by rivt.
[4] Files / Folders#
A rivt file is a Python plain text file ( .py ) that includes API functions and imports the rivtlib package into the rv namespace:
import rivtlib.rvapi as rv
rivt files are stored in either a rivt or rivtbk folder. Each rivt file and corresponding rivt doc has a prefix used for document organization. The top level folder structures are shown below. The difference in folder structure facilitates copying docs from rivtbooks into report. A more detailed description of the folder structure is here.
A report folder can contain any set of files and folders but the following structure is required for <i>doc</i> processing. Files and folders are organized under a root folder with the prefix rivt- e.g. rivt-Report-Label.
report folders (root folders) include at least the rivt files and the five required subfolders. Required folders and prefixes are shown in brackets. Folders preceded by an underscore contain rivt outputs. Folders requiring author input are capitalized.
The top level folder structure is shown below. More detailed descriptions of the folder structures are here.
Report Folders
--------------
[rivt-]Report-Label/ Report Folder
├── .help/ help files
├── .vscode/ optional VSCode settings
├── [_rivt-public]/ rivt-generated public files
└── [README.txt] text doc or report
├── [rvsrc]/ source files
├── [README.txt] public text report or doc
├── [rv-101-]filename1.py public rivt file
├── [rv-102-]filename2.py public rivt file
├── [rv-201-]filename3.py public rivt file
...
└── [rivt-report]/ rivt files and docs
├── [_published]/ published docs and reports
├── [_rstdocs]/ rivt generated rst files
├── [_rvstor]/ rivt generated stored files
├── [_rvsrc]/ author source files
├── [rivt-]report.py report generating script
├── [rv101-]filename1.py rivt file
├── [rv102-]filename2.py rivt file
├── [rv201-]filename3.py rivt file
...
rivtbook Folders
----------------
[rivtbk-]Book-Label/ rivtbook folder
├── .help/ help files
├── .vscode/ optional VSCode settings
├── [README.txt] rivt-generated book as text
├── [_rstdocs]/ restructured text files
├── [_pdfdocs]/ PDF docs and report
├── [rvbk101-]folder name rivtbook folder
├── [rvbk102-]folder name rivtbook folder
├── [rvbk201-]folder name rivtbook folder
...
[3] HTML and PDF Config (.py)#
The conf.py configuration file contains default 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
[4] PDF Style File (.yaml)#
The rivtstyle.yaml file contains default formats for PDF files.
fontsAlias: fontSerif: DejaVuSans fontSerifBold: DejaVuSans-Bold fontSerifBoldItalic: DejaVuSans-BoldOblique fontSerifItalic: DejaVuSans-Oblique fontMono: DejaVuSansMono fontMonoBold: DejaVuSansMono-Bold fontMonoBoldItalic: DejaVuSansMono-BoldOblique fontMonoItalic: DejaVuSansMono-Oblique fontSans: DejaVuSans fontSansBold: DejaVuSans-Bold fontSansBoldItalic: DejaVuSans-BoldOblique fontSansItalic: DejaVuSans-Oblique pageSetup: firstTemplate: coverPage height: null margin-bottom: 4mm margin-gutter: 1mm margin-left: 1.5cm margin-right: 1.5cm margin-top: 4mm size: letter spacing-footer: 10mm spacing-header: 10mm width: null pageTemplates: coverPage: showFooter: true showHeader: false underline: false noHead: frames: [[0%,0%,100%,100%]] showFooter: true showHeader: false underline: false mainPage: frames: [[0%,0%,100%,110%]] showFooter: True showHeader: True styles: base: allowWidows: 1 allowOrphans: 1 alignment: TA_LEFT allowOrphans: false allowWidows: false backColor: null borderColor: null borderPadding: 5 borderRadius: null borderWidth: 0 bulletFontName: fontMono bulletFontSize: 10 bulletIndent: 0 commands: [] firstLineIndent: 0 fontName: fontSans fontSize: 9 hyphenation: false leading: 12 leftIndent: 0 parent: null rightIndent: 0 spaceAfter: 1 spaceBefore: 1 strike: false textColor: black wordWrap: null linkUnderline: true linkColor: blue tableofcontents: parent: normal big-text: fontSize: 175% parent: base fontName: fontSans medium-text: fontSize: 125% parent: base fontName: fontSans small-text: fontSize: 125% parent: base fontName: fontSans blockquote: leftIndent: 20 parent: bodytext bodytext: alignment: TA_JUSTIFY hyphenation: true parent: normal spaceBefore: 6 align-center: alignment: TA_CENTER parent: bodytext align-right: alignment: TA_RIGHT parent: bodytext code: spaceBefore: 6 spaceAfter: 6 backColor: "#d1dede" borderColor: darkgray borderPadding: 6 borderWidth: 0.5 leftIndent: 0 parent: literal fontName: fontMonoBold compgreen: textColor: green alignment: TA_RIGHT fontName: fontSansBold compred: textColor: red alignment: TA_RIGHT fontName: fontSansBold contents: parent: normal figure: spaceBefore: 18 spaceAfter: 12 alignment: TA_CENTER colWidths: - 100% commands: - - VALIGN - - 0 - 0 - - -1 - -1 - TOP - - ALIGN - - 0 - 0 - - -1 - -1 - CENTER parent: bodytext figure-caption: alignment: TA_CENTER fontName: fontSans parent: bodytext figure-legend: parent: bodytext footer-box: alignment: TA_CENTER fontName: fontSans commands: - - BOX - - 0 - 0 - - -1 - -1 - 0.25 - white header-box: alignment: TA_RIGHT fontName: fontSans commands: - - BOX - - 0 - 0 - - -1 - -1 - 0.25 - white heading: keepWithNext: true parent: normal spaceAfter: 1 spaceBefore: 10 fontName: fontSerif textColor: "#222222" heading1: fontSize: 120% parent: heading fontName: fontSansBold underlineColor: black underlineWidth: 1 underlineOffset: 5 heading2: fontSize: 110% parent: heading fontName: fontSansBold underlineColor: black underlineWidth: 1 underlineOffset: 5 heading3: fontSize: 100% parent: heading heading4: parent: heading heading5: parent: heading heading6: parent: heading hint: parent: admonition hint-heading: parent: admonition-heading image: spaceBefore: 5 spaceAfter: 5 alignment: TA_CENTER parent: bodytext important: parent: admonition important-heading: parent: admonition-heading italic: fontName: fontSansItalic parent: bodytext line: parent: lineblock spaceBefore: 0 lineblock: parent: bodytext linenumber: parent: code literal: firstLineIndent: 0 fontName: fontMono hyphenation: false parent: normal wordWrap: null normal: parent: base note: parent: admonition note-heading: parent: admonition-heading option-list: colWidths: - null - null commands: - - VALIGN - - 0 - 0 - - -1 - -1 - TOP - - TOPPADDING - - 0 - 0 - - -1 - -1 - 0 rubric: alignment: TA_CENTER parent: bodytext textColor: darkred separation: parent: normal sidebar: backColor: cornsilk borderColor: darkgray borderPadding: 8 borderWidth: 0.5 float: none parent: normal width: 100% sidebar-subtitle: parent: heading4 sidebar-title: parent: heading3 subtitle: fontSize: 85% parent: title spaceBefore: 12 table: alignment: TA_LEFT spaceBefore: 1 spaceAfter: 1 borderPadding: 5 leftPadding: 6 rightPadding: 6 topPadding: 5 bottomPadding: 5 background-color: white alternate-row-background-color: lightgray commands: - - ROWBACKGROUNDS - - 0 - 0 - - -1 - -1 - - white - "#E0E0E0" - - BOX - - 0 - 0 - - -1 - -1 - 0.25 - black admonition: borderWidth: 0 borderPadding: 0 table-heading: alignment: TA_LEFT borderWidth: 0 borderPadding: 0 backColor: "#c5d1c5" borderColor: darkgray fontName: fontMonoBold tip-heading: parent: admonition-heading title: alignment: TA_CENTER fontSize: 120% keepWithNext: false parent: heading fontName: fontSansBold spaceAfter: 36 title-reference: fontName: fontSansItalic parent: normal toc: parent: normal fontSize: 100% toc1: fontName: fontSansBold parent: toc toc10: leftIndent: 100 parent: toc toc11: leftIndent: 100 parent: toc toc12: leftIndent: 100 parent: toc toc13: leftIndent: 100 parent: toc toc14: leftIndent: 100 parent: toc toc15: leftIndent: 100 parent: toc toc2: leftIndent: 20 parent: toc toc3: leftIndent: 40 parent: toc toc4: leftIndent: 60 parent: toc toc5: leftIndent: 80 parent: toc toc6: leftIndent: 100 parent: toc toc7: leftIndent: 100 parent: toc toc8: leftIndent: 100 parent: toc toc9: leftIndent: 100 parent: toc topic-title: parent: heading3 warning: parent: admonition warning-heading: parent: admonition-heading
[2] Comment Settings (.py)#
Comment settings are specified in the rivt file immediately following the import statement and before API methods, and are used to override default settings for the entire rivt doc. The rv private setting may be changed at the section level. If default settings shown in parenthesis are acceptable the comment settings are not needed.
See rivt markup for further details.