Changes between Version 5 and Version 6 of CodeCampIII/ScheduleAndWork/DocumentationWP


Ignore:
Timestamp:
Oct 4, 2016 7:38:19 AM (5 years ago)
Author:
butler
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • CodeCampIII/ScheduleAndWork/DocumentationWP

    v5 v6  
    1 == Documentation Tasks == 
    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 
     1Documentation 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:  
     2 
     3Documentation [[Rework Proposal]] 
     4 
     5Model [[Documentation Checks]] 
     6 
     7== Documentation Tasks Code Camp III == 
     8Proper 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 
    39 
    410At 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.