Dynamic Documentation Generation and 

Crowdsourcing in SasView

Brayden Miller

Dr. Paul Butler, Mentor Albert Einstein High School

SasView

Small angle scattering (SAS): What is it?

NEUTRONS

Detector

“NIST 2D NMR ‘fingerprinting’ Study Gives 

Biopharmaceutical Sector New Power to Assure 

High Quality Monoclonal Antibody Therapeutics.” 

NIST, December 21, 2018. 

https://www.nist.gov/newsevents/news/2018/12/nist-2d-nmrfingerprinting-study-gives-biopharmaceuticalsector-new-power. 

Background

Source

Sample Molecule

Scientists ask a question: 

WHAT ARE CHARACTARISITICS OF 

THIS MOLECULE?

ANALYSIS

Data

SAS is used to determine these 

characteristics, giving us data that must be 

analyzed. This can be done manually but is 

greatly enhanced using analysis software.

The NIST Center for Neutron 

Research (NCNR) works to 

supply both the equipment 

(shown left) and the analysis 

software necessary for modern 

SAS techniques.

SasView is a SAS software analysis suite.

▪ Capable of a wide variety of analysis operations

▪ Extensive documentation ~140 Pages, some ~6,000 

words

▪ Maintained by community

“NCNR East Guide Hall.” NIST, April 17, 2017. 

https://www.nist.gov/image/20170417016guidehalljpg.

SasView is an open-source, collaborative, and 

international project

Open source – READABLE AND CONTRIBUTABLE BY ALL

Collaborative – PROTECTED FROM THE “BUS FACTOR”

This means SasView is developed sustainably, with the goal that it 

can continue to be developed in the future. Unlike many 

alternative tools for SAS analysis, it has a consistent release cycle.

If a bus were to hit members of the 

developer team (or if they were to 

retire), the project will live on!

Ahmed, Adnan. “The Bus Factor.” Tajawal (blog), May 4, 

2018. https://medium.com/tech-tajawal/the-bus-factor6ea1a3ede6bd.

The Documentation Problem

SasView has three types of documentation, each with its own problems:

WHAT DOES DOCUMENTATION LOOK LIKE?

What we write

(not user-friendly) What we see

(user-friendly)

Compiling +

Formatting

Files are written in a mix of Restructured Text (ReST) and LaTeX for embedded 

mathematics. The viewable files are structured using HTML.

The Documentation Problem (cont’d)

What we write ✔️

What we see ❌

What we write❌

What we see ✔️

❌

Model

User

Documentation Developer

Outside scope of project

MODEL DOCUMENTATION

t1

t2

Fitting is a core analysis in SasView. If 

users know the general shape of their 

molecule, they can write an equation, 

called a model, to represent its shape. 

Variables in this model represent 

unknown parameters, like radius and 

length below.

I = f(t1 t2)

Researchers frequently write their own 

models and share them with the 

community. Writing documentation is 

possible, but it is not visible to users 

when ‘Help’ is pressed for their 

models.

User documentation assists users with the 

functionality of SasView and some of the 

theory involved in its calculations.

USER DOCUMENTATION

SASVIEW IS COLLABORATIVE

DOCUMENTATION MUST BE 

CONSTANTLY EVOLVING

We need to have an easy solution for letting the 

community edit documentation!

Users may see errors in documentation or be 

knowledgeable in an area of documentation and 

want to contribute. The current process involves:

▪ Using a GitHub account

▪ Cloning a repository

▪ Installing dependencies

▪ Running setup and config files via command line

▪ Edit raw RST documentation files by navigating 

source tree

▪ Running Makefile via command line to view HTML 

version

THIS IS TOO DIFFICULT OR TIME CONSUMING FOR A LARGE SET OF USERS!

Objective:

Make changes to 

ReST documentation

in SasView GUI editor

View changes

in HTML 

formatted docs

Submit corrected 

ReST files 

to developers

Functional

Easy to use

Minimal changes to code structure

Design Considerations:

Purpose is to lower barrier to entry

SasView is a large codebase, we need to 

develop sustainably

Before

Web Browser SasView

After Project

OPENS

SasView Documentation Viewer inside SasView

Help Button Pressed

Edit Button Pressed

Save Button Pressed

REFRESHES OPENS

OPENS

Functionality Included

Makefile

genmodel.py

ci.yml (Github Actions)

gentoc.py

RST Files

..\model\*.rst

HTML Files

..\_build\html

Sphinx

(via command line)

Formerly on

Summary

Accomplishments:

▪ Allow users to edit 

documentation locally

▪ Create opportunities for 

crowdsourcing SasView

▪ Documentation for community 

models is now visible

Bonus:

▪ Math will display 

regardless of 

browser settings

Future work:

▪ Automatic submission of edits 

to documentation

▪ Documentation regeneration 

scripts can be optimized

▪ Math still needs internet 

connection to display 

correctly