Version 7 (modified by butler, 5 years ago) (diff)

Documentation is an ongoing (never ending) process. Initial plans were drawn up in Code camp II to overhaul the infrastructure for developing and maintaining documentation and that infrastructure was mostly completed in code camp III along with an update to the usage documentation (not inclusive of the model documentation). At code camp IV the model documentation was overhauled as part of the process of moving to the sasmodels package and a plan for documentation in general was started as described in:

Documentation Rework Proposal

Model Documentation Checks

Documentation Tasks Code Camp III

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 finishing 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

Model documentation needs reviewing
General help needs writing
Documentation needs to be reviewed and updated
Smearing documentation could be improved
Fix auto build of sphinx documentation
Restructure documentation infrastructure - implement
Provide description of NIST 2D formats read by SasView
Fix License.txt
about page on web needs updating
Non Model Documentation needs to be ported to ReST
Integration of sasmodels documentation with SasView
Fix access to online documentation
clean up Jae-Hie's old website
Need to update wiki pages
Fix broken help on load image
Remove help_panel files and calls thereto
get models Detail button pointing to proper sphinx documentation
Finish porting old html help docs to rst
Proof read Sphinx help docs
Several model file docstrings are incorrectly formatted
Possible inconsistency in Poly_GaussCoil model
Add panel help to each too item
Add documentation for BUMPS usage and integrate rst files to SasView from BUMPS repo
Need new tutorial documentation
Need BUMPS usage documentation
Missing documentation about residual plot (and fit plot)
Missing documentation for custom model editors
Do we use libxml2?
Enhance help (non model) documentation
Restructure top level of documentation window in application
simultaneous/constrained fit page does not have help button
Build PDF documentation along with HTML
Restructure Document tree in User Documentation
Add Menu Help to User Documentation
Remove all references to "perspective" from User Documentation
Review User Documentation
SasView Menu bar clarity
Add Pr Tutorial module
Add Invariant Tutorial Module
Add 1D model fitting tutorial
Add 2D model fitting Tutorial
Add constrained fit Tutorial
Add simultaneous fitting tutorial
Add Batch Fitting Tutorial
What should we do with the (short) model description?
Integrated documentation tocs need manual updating when new models are added
Get rid of .copy files when happy with docs
Upgrade Sphinx version used in docs builds
sasmodels docs should not refer to documentation in SasView
#555 needs cleanup
Need to document Combine Batch Fit
surface fractal I(q) < 0
update plotting documentation to reflect new range option and text box positioning
Check all model documentation for standardization
Pr documentation standardization and updating
Need to add minimum documentation on writing new models
Update plugin model documentation and testing
Write/enhance gpu_computation.rst
Update About window
Update Acknowledgement window
Push new documentation to the website
Update data_formats.rst when File Converter branch merged
Update the test data documentation
Incorporate instructions for running the SESANS GUI
Review new GPU and OpenCL documentation
Review new Corfunc documentation
Review new File Converter documentation
Link to documentation on available library routines
Improve smearing help
sin(alpha) documentation issues for some cylinder types
Add notes to doc about fitting integer parameters
Add link to source code of each model to model documentation
Sort out developer documentation / wiki
DOC: SlitlengthCalculator needs to be documented
Need to add Diamond developer and logo in relevant places
Provide new tutorial materials
Slurp tutorial repo for tutorials
Build new tutorials as PDF
Build new tutorials as HTML
Build new tutorials as eBook
Include sasmodels api docs in sasview developer documentation
Consider releasing new tutorial in 4.1.1
Possible problem with new doc build process
Should we use Dispersity instead of Polydispersity/Monodispersity?
add PDF documentation to website and document in wiki release process
Check plugin & orientation descriptions in full docs once SasModels PR #57 is merged
"Writing a Plugin Model" does not explain function "random"
AutoPlot generation for model documentation does not include background
Missing Docs and Help for new Batch Slicing
Intro to scripting.rst needs improvement
Documentation for S(Q) models need updating
Clarify the documentation for the Spinodal Model
Need to rethink Tutorial option in GUI Help menu
S(Q) models need function descriptions in documentation
documentation for magnetism need update
Update correlation function documentation re non-Lorentz-corrected data
Copy over pdfs of updated correlation function tutorial before 4.2.1 release
RELEASE.html needs updating before 4.2.1 release
Copy updated corfunc_help to Github for new website docs
Many models do not have their equation in the documentation
Clarify no longer any pure python orientation/magnetism plugin support in docs
Change source links in model docs to local paths

Tasks - ALL DONE

  • 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. This will be a forever ongoing maintenance task. However the initial restructuring and implementation is - DONE
  • 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: DONE
  • convert eqations from images to TeX - Peter Parker to do first then Paul Kienzle: DONE
  • Split the models documentation — wait to see how new model structure works. - DONE
  • Integrate into GUI - Paul Kienzle Plus all developers: DONE
  • For models make example/test data/output self generate from the model itself. This will be a forever ongoing maintenance task. However the initial restructuring and implementation is - DONE


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