E.1 | Collaboration#

[1] Overview#

There are several ways to collaborate on writing and improving rivt docs, and to contribute to improvements of rivtlib and rivt frameworks.

1. Upload public rivt files to GitHub and Google Drive

Public rivt files may be collaboratively improved by:

  • forking to create different or improved versions of rivt files.

  • providing pull requests.

  • submitting issues and bugs.

Public rivt files are generated by rivtlib through a setting on each rivt file section. The files are stored in the _rivt-public folder which may be uploaded to a public GitHub repository. rivt also publishes the formatted text form of the rivt doc or report to a README.txt file. When the _rivt-public folder is uploaded to a repository, the README is displayed on the landing page and can be searched across all GitHub using a search interface.

rivt public folder structure

[rivt-]folder-label/          report folder
    ├── .vscode/                    optional VSCode settings
    ├── README.txt                  rivt-generated report
    ├── [_rivt-public]/                 public subset of rivt files
        ├── rvsrc/
        ├── README.txt
        ├── rv-101-filename1.py
        ├── rv-102-filename2.py
        ├── rv-201-filename3.py
        ...

[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.

Packages and extensions are summarized here and here.

3. Contribute to rivt frameworks

As a Python file, rivt can work efficiently with a large variety of programs using scripts and shell commands. Frameworks are collections of programs and scripts that facilitate the use of rivt with other programs. The basic and extended frameworks are described here.

The generality of rivt allows for the developement of domain-specific frameworks that include programs and scripts for that domain. For example, a rivt structural engineering framework could include scripts for running, pre- and post-processing:

4. Real-time Collaboration

Within an IDE or cloud environment, rivt files can be collaboratively developed and edited.

Examples include:

Visual Studio Live Share.

and

CodeSpaces

[2] Public Google Drive files#

For each rivt file that is published a corresponding public rivt file is written to the public folder. The default contents of the file are the API rivt string headers. If the header parameter public is included in the header, the rivt string content is also written to the public rivt file.

The public folder can be uploaded to a public repository and updated with Git as the project develops.

The web site OpenModels.info is a Google Drive repository of open source engineernig model files, including rivt files and reports.