CodeCampIII_ScheduleAndWork_DocumentationWP

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

SasView/sasview#1285 : 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???