[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 neteler):

 Replying to [comment:28 hamish]:
 > Replying to [comment:23 neteler]:
 ...
 > It seems like a problem solved over and over again in the mid 90s (which
 really shows in htDig's cosmetics). There must be a better local site
 search package available.

 Maybe, but I spent too much lifetime on this already.

 ...
 > > and sphinx seems to provide it as it does for many OSGeo projects.
 >
 > I'd enjoy seeing sphinx in parallel with the html docs and available,
 they look great,

 There seems to be a misunderstanding. The proposal is to *keep* the
 current HTML docs since the new sphinx mechanism uses them as input.

 The point is to offer the resulting HTML pages on the server as well
 as to the user in local, no problems to have two offerings here
 ("classical" HTML pages and the "new" ones).


 > As mentioned earlier, my other concern is to throw away all the strong
 markup and hand crafting (including <br>s) that has gone into the html
 description.htmls,

 Sure, nobody said this. I just pointed out that there are HTML errors
 in the current HTML pages which need to be fixed anyway (and which will
 make
 pandoc more happy). I am surprised that some of these pass the W3
 validator.

 ...
 > And pandoc -> LaTeX -> a better PDF booklet while we're at it.

 Yes if they don't become a 1000 pages manual which then will be printed
 and kill the rain forest.

 > Replying to [comment:24 neteler]:
 > > While I agree, we have many places where <br> is probably abused, i.e.
 > > in <li> lists and other odd places. pandoc is basically complaining
 about
 > > these suboptimal use cases.
 >
 > do the pages pass proper html validation checks?

 Strangely yes. See for example r52667 for changes which improve the
 current HTML and which help pandoc as well.


 > Or is pandoc not fully supporting valid html &/or brittle in how it
 does? if so, perhaps a 'sed -e 's+<br>+<br />+g' pre-processing step (etc)
 piped in as passing the files to pandoc would work around that deficiency
 in pandoc, until such time as pandoc is fixed.

 ... your suggestion needs to be tested.


 > Local off-line search of the help pages is a nice goal, e.g. for use
 from a laptop in the field.

 Also: not all people in the world are always online... a searchable
 user manual is a must have nowadays. Especially when offering 400
 modules.

 Markus

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