Documentation Tasks

Proper documentation has long been identified as a critical, yet often overlooked, component for usable and sustainable software. Currently (as of 3.0) most of the developer docs which are in the files as docstrings do not get scrapped properly. Moreover the docs strings are extremely limited and sometimes unhelpful. From the user documentation perspective there is a lot of poorly written and confusing documentation as well as obsolete documentation. Editing this is currently a nightmare as it is in a big html file generated from a word file containing tons of extraneous characters. Further the equations are given as images making them either large files or poor (and ugly - non professional) quality) and more importantly hard to change if an error is found. This has essentially frozen and documentation fixing and additions. Thus fiinshing the documentation infrastructure is identified as a critical task for sasview code camp III

At code camp II it was agreed that we would move to using Sphinx to generate all documentation. First getting sphinx to build the developer documentation properly. For user documentation we would turn all HTML help docs into ReST format. Equations should be converted to TeX format. Then a sphinx script made to generate an html output from those files with each build allowing for simple editing of documentation and constant updated documentation available both on the web and in the GUI.

Unfortunately to do the above requires moving to Wx3.0 which has proper html support

#19

Model documentation needs reviewing

#20

General help needs writing

#32

Documentation needs to be reviewed and updated

#33

Smearing documentation could be improved

#202

Fix auto build of sphinx documentation

#221

Restructure documentation infrastructure - implement

#226

Provide description of NIST 2D formats read by SasView

#240

Fix License.txt

#257

about page on web needs updating

#297

Non Model Documentation needs to be ported to ReST

#318

Integration of sasmodels documentation with SasView

#323

Fix access to online documentation

#326

clean up Jae-Hie's old website

#327

Need to update wiki pages

#337

Fix broken help on load image

#338

Remove help_panel files and calls thereto

#339

get models Detail button pointing to proper sphinx documentation

#355

Finish porting old html help docs to rst

#356

Proof read Sphinx help docs

#360

Several model file docstrings are incorrectly formatted

#364

Possible inconsistency in Poly_GaussCoil model

#367

Add panel help to each too item

#378

Add documentation for BUMPS usage and integrate rst files to SasView from BUMPS repo

#387

Need new tutorial documentation

#388

Need BUMPS usage documentation

#389

Missing documentation about residual plot (and fit plot)

#404

Missing documentation for custom model editors

#412

Do we use libxml2?

#422

Enhance help (non model) documentation

#436

Restructure top level of documentation window in application

#479

simultaneous/constrained fit page does not have help button

#510

Build PDF documentation along with HTML

#511

Restructure Document tree in User Documentation

#512

Add Menu Help to User Documentation

#513

Remove all references to "perspective" from User Documentation

#514

Review User Documentation

#515

SasView Menu bar clarity

#516

Add Pr Tutorial module

#517

Add Invariant Tutorial Module

#518

Add 1D model fitting tutorial

#519

Add 2D model fitting Tutorial

#520

Add constrained fit Tutorial

#521

Add simultaneous fitting tutorial

#522

Add Batch Fitting Tutorial

#528

What should we do with the (short) model description?

#545

Integrated documentation tocs need manual updating when new models are added

#546

Get rid of .copy files when happy with docs

#550

Upgrade Sphinx version used in docs builds

#554

sasmodels docs should not refer to documentation in SasView

#555

build_sphinx.py needs cleanup

#597

Need to document Combine Batch Fit

#606

surface fractal I(q) < 0

#621

update plotting documentation to reflect new range option and text box positioning

#646

Check all model documentation for standardization

#647

Pr documentation standardization and updating

#651

Need to add minimum documentation on writing new models

#668

Update plugin model documentation and testing

#680

Write/enhance gpu_computation.rst

#692

Update About window

#693

Update Acknowledgement window

#699

Push new documentation to the website

#709

Update data_formats.rst when File Converter branch merged

#710

Update the test data documentation

#720

Incorporate instructions for running the SESANS GUI

#734

Review new GPU and OpenCL documentation

#735

Review new Corfunc documentation

#736

Review new File Converter documentation

#772

Link to documentation on available library routines

#833

Improve smearing help

#834

sin(alpha) documentation issues for some cylinder types

#882

Add notes to doc about fitting integer parameters

#883

Add link to source code of each model to model documentation

#886

Sort out developer documentation / wiki

#897

DOC: SlitlengthCalculator needs to be documented

#913

Need to add Diamond developer and logo in relevant places

#928

Provide new tutorial materials

#934

Slurp tutorial repo for tutorials

#935

Build new tutorials as PDF

#936

Build new tutorials as HTML

#937

Build new tutorials as eBook

#947

Include sasmodels api docs in sasview developer documentation

#955

Consider releasing new tutorial in 4.1.1

#956

Possible problem with new doc build process

#1003

Should we use Dispersity instead of Polydispersity/Monodispersity?

#1021

add PDF documentation to website and document in wiki release process

#1054

Check plugin & orientation descriptions in full docs once SasModels PR #57 is merged

#1108

"Writing a Plugin Model" does not explain function "random"

#1128

AutoPlot generation for model documentation does not include background

#1139

Missing Docs and Help for new Batch Slicing

#1141

Intro to scripting.rst needs improvement

#1148

Documentation for S(Q) models need updating

#1167

Clarify the documentation for the Spinodal Model

#1175

Need to rethink Tutorial option in GUI Help menu

#1187

S(Q) models need function descriptions in documentation

#1190

documentation for magnetism need update

#1225

Update correlation function documentation re non-Lorentz-corrected data

#1227

Copy over pdfs of updated correlation function tutorial before 4.2.1 release

#1228

RELEASE.html needs updating before 4.2.1 release

#1229

Copy updated corfunc_help to Github for new website docs

#1240

Many models do not have their equation in the documentation

#1253

Clarify no longer any pure python orientation/magnetism plugin support in docs

#1263

Change source links in model docs to local paths

Tasks

• Move to Wx3.0 - DONE
• Get Sphinx to properly build all the docstrings and produce user documentation pushed to website at every build - Peter Parker: DONE
• Clean up and add developer documentation to modules - ….
• Get Sphinx to collect all RST documentation in various folders and create user documentation pushed to website on every build AND available in SasView? application directly - Peter Parker: DONE
• copy all model documentation to ReST files - Steve King: DONE
• copy all remaining documentation into ReST files (except for PDF tutorial for now which will need rewriting) - Steve King (lead) and Paul Butler
• convert eqations from images to TeX - Peter Parker to do first then Paul Butler
• Split the models documentation — wait to see how new model structure works
• Integrate into GUI - Paul Butler
• For models make example/test data/output self generate from the model itself ….

Developers

• Steve King
• Peter Parker
• Paul Butler
• SAS models refactoring team???