Changes between Version 4 and Version 5 of CodeCampIII/ScheduleAndWork/DocumentationWP
- Timestamp:
- Feb 14, 2015 8:43:28 AM (10 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
CodeCampIII/ScheduleAndWork/DocumentationWP
v4 v5 1 1 == Documentation Tasks == 2 One of the key priorities for long term sustainability and user support and uptake is proper documentation. 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 2 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 3 4 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. 5 6 Unfortunately to do the above requires moving to Wx3.0 which has proper html support 3 7 4 8 … … 6 10 7 11 Tasks 8 * Get Sphinx to properly build all the docstrings and produce user documentation pushed to website at every build - '''DONE''' 12 * Move to Wx3.0 - '''DONE''' 13 * Get Sphinx to properly build all the docstrings and produce user documentation pushed to website at every build - '''Peter Parker: DONE''' 9 14 * Clean up and add developer documentation to modules - .... 10 * 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 - DONE 11 * copy all remaining documentation into ReST files (except for PDF tutorial for now which will need rewriting) - S. King (lead) and P. Butler 12 * convert eqations from images to TeX - Peter Parker to do first then Paul Butler 15 * 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''' 16 * copy all model documentation to ReST files - '''Steve King: DONE''' 17 * copy all remaining documentation into ReST files (except for PDF tutorial for now which will need rewriting) - '''Steve King (lead) and Paul Butler''' 18 * convert eqations from images to TeX - Peter Parker to do first then '''Paul Butler''' 13 19 * Split the models documentation -- wait to see how new model structure works 14 * Integrate into GUI - Paul Butler 20 * Integrate into GUI - '''Paul Butler''' 21 * For models make example/test data/output self generate from the model itself .... 15 22 16 23 == Developers == … … 18 25 - Peter Parker 19 26 - Paul Butler 27 - SAS models refactoring team???
