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

 Replying to [comment:22]:
 @Luca: sorry I'm not much of a Makefile expert, but does the command
 exiting with an error not break out of the 'make' job right away?
 A "make restdocs" would be nice.


 Replying to [comment:23 neteler]:
 > Replying to [comment:18 hamish]:
 > ...
 > > I don't think lack of a working htDig install*, or reliance on "site:"
 google search, is a fatal blow for html.
 > >
 > > [*] (is that still the case? if so as offered earlier, I'm happy to
 spend a little time on it)
 >
 > htDig is missing for many years now (unfortunately) and google search is
 poor (unfortunately). A better solution is definitely needed

 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.... we could pour hours of time into getting
 htDig working but at the end of the day it's still htDig, which I'm not
 sure of others' impressions of but I never really found too visually
 pleasing. Ideally there would be some tool which we could configure to
 also search the grass5 docs etc, but move those results all the way down
 to the end of page 17, with the grass 6.4 hits returning first.

 > 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, but they do take up more space and subtle things like two
 spaces in front of ".." instead of three, or not enough whitespace around
 "*" bullet points can cause your next paragraph to silently not display,
 with no error logged in the build messages (something I was fighting with
 two days ago, after a work-day of fighting with whitespace in fortran77
 code). I just think we should be careful with the word "replace" the html
 docs at this point. 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, as ReSt's markup is by design much
 looser and sensitive. To keep (valid!) html as the source for those and
 converting to ReSt automatically with panodoc (IIUC how this is intended
 to work) would be great. The more the merrier. And pandoc -> LaTeX -> a
 better PDF booklet while we're at it.

 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? I typically set my
 GRASS_HTML_BROWSER to dillo with the htmlbug validation tool turned on to
 test as I work.

 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.

 Replying to [comment:27 glynn]:
 > Beyond that, I don't really see the point of adding another dependency.

 we have an optional make pdfdocs, why not an optional make restdocs too
 and host them somewhere? If it all works well & is self contained we can
 look at bundling the same with the binary installers, e.g. as with the new
 grass-dev-doc package for debian which ships the programmers' manual.

 Again, we should be careful with our use of the word "replace"; perhaps
 "augment" the current offerings is a better term for now? Local off-line
 search of the help pages is a nice goal, e.g. for use from a laptop in the
 field. (perhaps there is some python-html grepping library we could use?)


 shrug,
 Hamish

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