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

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

Developers

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