[GRASS-dev] [GRASS GIS] #151: make documentation be full text searchable: use sphinx

[GRASS GIS]

#151: make documentation be full text searchable: use sphinx
-------------------------+--------------------------------------------------
 Reporter:  timmie       |       Owner:  epatton    
     Type:  enhancement  |      Status:  assigned   
 Priority:  major        |   Milestone:  7.0.0      
Component:  Website      |     Version:  unspecified
 Keywords:               |    Platform:  Unspecified
      Cpu:  Unspecified  |  
-------------------------+--------------------------------------------------

Comment(by wenzeslaus):

 Replying to [comment:30 glynn]:
 > In which case, what is the point of the --rest-description option? Also,
 Rest.make, restdir target, etc? IOW, why does the ReST generation require
 anything other than the generated HTML files in
 dist.<arch>/docs/html/*.html?

 The generated HTML files (in dist.<arch>/docs/html/*.html) are not enough
 because for example parameter list is represented as HTML description but
 ReST has its own representation of the parameter list
 ([http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
 #option-lists ReST option list]). Once module description is converted to
 HTML the information whether this description list is module parameter
 list or some general list in hand-written module description (module.html
 file) is lost.

 The conversion of complete generated HTML files (in
 dist.<arch>/docs/html/*.html) is possible but there are only two options.
 The first one is the usage of a generic converter (as is now used for
 module.html files) but any clever standard formatting in ReST cannot be
 used. The second one is to create a custom (context aware) transformation
 which uses both HTML markup and contents (e.g. contents of <h2> tag) but
 this can be a lot of work (I've tried it using XSLT but I gave it up).
 Another option would be to use XSLT and generated XML description but
 direct generation of ReST description seems like a less complex solution
 for me.

-- 
Ticket URL: <https://trac.osgeo.org/grass/ticket/151#comment:31>
GRASS GIS <http://grass.osgeo.org>