[GRASS-dev] [GRASS GIS] #151: make documentation be full text searchable: use sphinx
trac at osgeo.org
Wed Aug 15 19:22:48 PDT 2012
#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 |
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
> 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?)
Ticket URL: <https://trac.osgeo.org/grass/ticket/151#comment:28>
GRASS GIS <http://grass.osgeo.org>
More information about the grass-dev