first implementation of restructredtext documentation

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@52656 15284696-431f-4ddb-bdfa-cd5b030d7da7

db/Makefile

@@ -27,3 +27,7 @@ htmldir:
 	$(MAKE) -C drivers
 	$(MAKE) parsubdirs
 
+restdocs: restdir
+
+restdir: $(MAKE) parsubdirs
+

display/Makefile

@@ -45,3 +45,7 @@ include $(MODULE_TOPDIR)/include/Make/Dir.make
 default: htmldir
 
 htmldir: parsubdirs
+
+restdocs: restdir
+
+restdir: parsubdirs

doc/Makefile

@@ -6,3 +6,4 @@ include $(MODULE_TOPDIR)/include/Make/Dir.make
 
 default: htmldir
 
+restdocs: $(MAKE) restdir

general/Makefile

@@ -35,3 +35,6 @@ include $(MODULE_TOPDIR)/include/Make/Dir.make
 
 default: parsubdirs
 
+restdocs: restdir
+
+restdir: parsubdirs

imagery/Makefile

@@ -47,3 +47,7 @@ default: htmldir
 
 htmldir: parsubdirs
 
+restdocs: restdir
+
+restdir: parsubdirs
+

imagery/i.find/Makefile

@@ -7,6 +7,7 @@ DEPENDENCIES = $(GISDEP)
 
 include $(MODULE_TOPDIR)/include/Make/Etc.make
 include $(MODULE_TOPDIR)/include/Make/NoHtml.make
+include $(MODULE_TOPDIR)/include/Make/NoRest.make
 
 default: etc
 

include/Make/DB.make

@@ -7,11 +7,16 @@ include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
 include $(MODULE_TOPDIR)/include/Make/Compile.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
 dbmi: $(DBDRIVERDIR)/$(PGM)$(EXE) db_html
 
 db_html: $(HTMLDIR)/grass-$(PGM).html $(MANDIR)/grass-$(PGM).$(MANSECT)
 
+restdocs: $(DBDRIVERDIR)/$(PGM)$(EXE) db_rest
+
+db_rest: $(RESTDIR)/grass-$(PGM).txt
+
 $(DBDRIVERDIR)/$(PGM)$(EXE): $(ARCH_OBJS) $(DEPENDENCIES)
 	$(call linker)
 

include/Make/Dir.make

@@ -4,6 +4,7 @@
 include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
 # don't install *.png, *.jpg for directories
 # to prevent problems with r.out.png etc
@@ -40,6 +41,8 @@ depend: depend-recursive
 
 htmldir: html
 
+restdir: rest
+
 .PHONY: subdirs parsubdirs htmldir $(SUBDIRS)
 
 parsubdirs: $(SUBDIRS)

include/Make/Docs.make

@@ -102,5 +102,23 @@ changelog:
 	fi
 	sh svn2cl ./ChangeLog
 
+rest_dirs = \
+	db \
+	general \
+	imagery \
+	ps \
+	raster \
+	raster3d \
+	scripts \
+	temporal \
+	vector \
+
+restdocs:
+	$(MAKE)
+	$(MKDIR) $(RESTDIR)
+	for dir in $(rest_dirs) ; do \
+	  $(MAKE) -C $$dir rest ; \
+	  done
+
 .PHONY: htmldocs-single htmldocs packagehtmldocs pdfdocs cleandocs html2pdfdoc
 .PHONY: html2pdfdoccomplete changelog

include/Make/Etc.make

@@ -9,8 +9,9 @@ include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
 include $(MODULE_TOPDIR)/include/Make/Compile.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
-etc: $(ETC)/$(PGM)$(EXE) html
+etc: $(ETC)/$(PGM)$(EXE) html rest
 
 $(ETC)/$(PGM)$(EXE): $(ARCH_OBJS) $(DEPENDENCIES)
 	$(call linker)

include/Make/Grass.make

@@ -56,6 +56,7 @@ DRIVERDIR       = $(ARCH_DISTDIR)/driver
 DBDRIVERDIR     = $(ARCH_DISTDIR)/driver/db
 DOCSDIR         = $(ARCH_DISTDIR)/docs
 HTMLDIR         = $(ARCH_DISTDIR)/docs/html
+RESTDIR         = $(ARCH_DISTDIR)/docs/rest
 SCRIPTDIR       = $(ARCH_DISTDIR)/scripts
 MSG_DIR         = $(ARCH_DISTDIR)/etc/msgs
 MO_DIR          = $(ARCH_DISTDIR)/locale

include/Make/Lib.make

@@ -8,6 +8,7 @@ include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
 include $(MODULE_TOPDIR)/include/Make/Compile.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
 ifneq ($(LIB),)
 LIB_NAME := $($(LIB)_LIBNAME)
@@ -24,3 +25,6 @@ include $(MODULE_TOPDIR)/include/Make/Shlib.make
 
 lib: $(GRASS_LIBRARY_TYPE)
 	if [ "$(PGM)" != "" -a -f "$(PGM)".html ] ; then $(MAKE) html ; fi
+
+lib: $(GRASS_LIBRARY_TYPE)
+	if [ "$(PGM)" != "" -a -f "$(PGM)".html ] ; then $(MAKE) rest ; fi

include/Make/Module.make

@@ -9,8 +9,11 @@ include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
 include $(MODULE_TOPDIR)/include/Make/Compile.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
-cmd: $(BIN)/$(PGM)$(EXE) html
+cmd: $(BIN)/$(PGM)$(EXE) html restdocs
+
+restdocs: $(BIN)/$(PGM)$(EXE) rest
 
 $(BIN)/$(PGM)$(EXE): $(ARCH_OBJS) $(DEPENDENCIES)
 	$(call linker)

include/Make/Multi.make

@@ -5,6 +5,7 @@ include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
 include $(MODULE_TOPDIR)/include/Make/Compile.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
 PROGFILES = $(patsubst %,$(BIN)/%$(EXE),$(PROGRAMS))
 HTMLFILES = $(patsubst %,$(HTMLDIR)/%.html,$(PROGRAMS))

include/Make/NoRest.make

@@ -0,0 +1,3 @@
+
+$(RESTDIR)/$(PGM).txt:
+	@echo no REST documentation available

include/Make/Other.make

@@ -1,4 +1,5 @@
 include $(MODULE_TOPDIR)/include/Make/Vars.make
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 

include/Make/Rest.make

@@ -0,0 +1,38 @@
+
+# generic rest rules for all commands
+
+ifdef CROSS_COMPILING
+
+rest:
+
+else
+
+#check for program
+checkpandoc:
+	@(type pandoc > /dev/null || (echo "ERROR: Install 'pandoc' software first (get from http://johnmacfarlane.net/pandoc/)" && exit 1))
+
+restdesc = $(call run_grass,$(1) --rest-description < /dev/null > $(2)) || exit 0
+
+IMGSRC := $(wildcard *.png) $(wildcard *.jpg)
+IMGDST := $(patsubst %,$(RESTDIR)/%,$(IMGSRC))
+
+$(RESTDIR)/%.txt: %.html %.tmp.txt $(HTMLSRC) $(IMGDST) | $(RESTDIR)
+	$(PYTHON) $(GISBASE)/tools/mkrest.py $* $(GRASS_VERSION_DATE) > $@;
+ifneq ($(strip $(IMGDST)),)
+.SECONDARY: $(IMGDST)
+endif
+
+$(RESTDIR)/%.png: %.png | $(RESTDIR)
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/%.jpg: %.jpg | $(RESTDIR)
+	$(INSTALL_DATA) $< $@
+
+%.tmp.txt: $(HTMLSRC)
+	if [ "$(HTMLSRC)" != "" ] ; then $(call restdesc,$<,$@) ; fi
+
+rest: $(RESTDIR)/$(PGM).txt # checkpandoc
+
+endif
+
+.PHONY: rest

include/Make/Rules.make

@@ -6,7 +6,7 @@ first: pre default
 ARCH_DIRS = $(ARCH_DISTDIR) $(ARCH_BINDIR) $(ARCH_INCDIR) $(ARCH_LIBDIR) \
 	$(BIN) $(ETC) \
 	$(DRIVERDIR) $(DBDRIVERDIR) $(FONTDIR) $(DOCSDIR) $(HTMLDIR) \
-	$(MANBASEDIR) $(MANDIR) $(TOOLSDIR)
+	$(MANBASEDIR) $(MANDIR) $(TOOLSDIR) $(RESTDIR)
 
 pre: | $(ARCH_DIRS)
 

include/Make/Script.make

@@ -12,8 +12,9 @@ HTMLSRC = $(SCRIPT)
 include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Html.make
 include $(MODULE_TOPDIR)/include/Make/ScriptRules.make
+include $(MODULE_TOPDIR)/include/Make/Rest.make
 
-SCRIPT_ACTIONS = $(SCRIPT) html scriptstrings
+SCRIPT_ACTIONS = $(SCRIPT) html scriptstrings rest
 
 script: $(SCRIPT_ACTIONS)
 
@@ -22,6 +23,7 @@ scriptstrings: $(STRINGDIR)/$(PGM)_to_translate.c
 install:
 	$(INSTALL) $(SCRIPT) $(INST_DIR)/scripts/
 	$(INSTALL_DATA) $(HTMLDIR)/$(PGM).html $(INST_DIR)/docs/html/
+	$(INSTALL_DATA) $(HTMLDIR)/$(PGM).txt $(INST_DIR)/docs/rest/
 	$(INSTALL_DATA) $(ARCH_DISTDIR)/docs/man/man1/$(PGM).1 $(INST_DIR)/docs/man/man1/
 	if [ -d "$(ETC)/$(PGM)" ] ; then \
 		cp -rL $(ETC)/$(PGM) $(INST_DIR)/etc/ ; \

lib/gtcltk/Makefile

@@ -3,6 +3,7 @@ MODULE_TOPDIR = ../..
 PGM=grocat
 include $(MODULE_TOPDIR)/include/Make/Etc.make
 include $(MODULE_TOPDIR)/include/Make/NoHtml.make
+include $(MODULE_TOPDIR)/include/Make/NoRest.make
 
 TCLSRC := $(wildcard *.tcl)
 TCLDST := $(patsubst %.tcl,$(ETC)/gtcltk/%.tcl,$(TCLSRC))

lib/vector/Makefile

@@ -18,6 +18,10 @@ default: htmldir
 
 htmldir: parsubdirs
 
+restdocs: restdir
+
+restdir: parsubdirs
+
 diglib: rtree
 
 Vlib: rtree dglib diglib

man/Makefile

@@ -11,6 +11,16 @@ DSTFILES := \
 	$(HTMLDIR)/nviz/grassdocs.css \
 	$(HTMLDIR)/nviz/grass_logo.png
 
+DSTFILES_REST := \
+	$(RESTDIR)/grassdocs.css \
+	$(RESTDIR)/grass_logo.png \
+	$(RESTDIR)/grass_icon.png \
+	$(RESTDIR)/nviz/grassdocs.css \
+	$(RESTDIR)/nviz/grass_logo.png \
+	$(RESTDIR)/conf.py \
+	$(RESTDIR)/make.bat \
+	$(RESTDIR)/Makefile \
+
 categories = \
 	d:display \
 	db:database \
@@ -29,13 +39,21 @@ IDXSRC = full_index index $(IDXCATS)
 
 INDICES := $(patsubst %,$(HTMLDIR)/%.html,$(IDXSRC))
 
+INDICES_REST := $(patsubst %,$(RESTDIR)/%.txt,$(IDXSRC))
+
 ALL_HTML := $(wildcard $(HTMLDIR)/*.*.html)
 
+ALL_REST := $(wildcard $(RESTDIR)/*.*.txt)
+
 default: $(DSTFILES)
 	@echo "Generating HTML manual pages index (help system)..."
 	$(MAKE) $(INDICES)
 	$(call build,check)
 	$(MAKE) manpages
+	$(MAKE) restdocs
+
+restdocs: $(DSTFILES_REST)
+	  $(MAKE) $(INDICES_REST)
 
 # This must be a separate target so that evaluation of $(MANPAGES)
 # is delayed until the indices have been generated
@@ -48,18 +66,33 @@ define build
 GISBASE="$(RUN_GISBASE)" ARCH="$(ARCH)" ARCH_DISTDIR="$(ARCH_DISTDIR)" $(PYTHON) ./build_$(1).py $(2)
 endef
 
+define build_rest
+GISBASE="$(RUN_GISBASE)" ARCH="$(ARCH)" ARCH_DISTDIR="$(ARCH_DISTDIR)" $(PYTHON) ./build_$(1)_rest.py $(2)
+endef
+
 $(HTMLDIR)/full_index.html: $(ALL_HTML) build_full_index.py build_html.py
 	$(call build,full_index)
 	touch $@
 
+$(RESTDIR)/full_index.txt: $(ALL_REST) build_full_index_rest.py build_rest.py
+	$(call build_rest,full_index)
+	touch $@	
+
 $(HTMLDIR)/index.html: build_index.py build_html.py
 	$(call build,index)
 	touch $@
 
+$(RESTDIR)/index.txt: build_index_rest.py build_rest.py
+	$(call build_rest,index)
+	touch $@	
+
 define category_rule
 $$(HTMLDIR)/$(2).html: $$(wildcard $$(HTMLDIR)/$(1).*.html) build_class.py build_html.py
 	$$(call build,class,$(1) $(2))
 	touch $$@
+$$(RESTDIR)/$(2).txt: $$(wildcard $$(RESTDIR)/$(1).*.txt) build_class_rest.py build_rest.py
+	$$(call build_rest,class,$(1) $(2))
+	touch $$@
 endef
 
 $(foreach cat,$(categories),$(eval $(call category_rule,$(firstword $(subst :, ,$(cat))),$(lastword $(subst :, ,$(cat))))))
@@ -82,3 +115,30 @@ $(HTMLDIR)/grass_icon.png: grass_icon.png
 $(HTMLDIR)/nviz:
 	$(MKDIR) $@
 
+$(RESTDIR)/grassdocs.css: grassdocs.css
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/nviz/grassdocs.css: grassdocs.css | $(RESTDIR)/nviz
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/grass_logo.png: grass_logo.png
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/nviz/grass_logo.png: grass_logo.png | $(RESTDIR)/nviz
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/grass_icon.png: grass_icon.png
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/conf.py: sphinx/conf.py
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/make.bat: sphinx/make.bat
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/Makefile: sphinx/Makefile
+	$(INSTALL_DATA) $< $@
+
+$(RESTDIR)/nviz:
+	$(MKDIR) $@
+

man/build_check_rest.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+
+# checks for HTML files missing DESCRIPTION section
+# (c) The GRASS Development Team, Markus Neteler, Glynn Clements 2003, 2004, 2005, 2006, 2009
+
+import sys
+import os
+import string
+
+from build_rest import *
+
+os.chdir(rest_dir)
+
+sys.stdout.write(message_tmpl.substitute(rest_dir = rest_dir))
+
+for cmd in rest_files('*'):
+    if "DESCRIPTION" not in read_file(cmd):
+	sys.stdout.write("%s\n" % cmd[:-5])
+
+sys.stdout.write(r"""
+----------------------------------------------------------------------
+""")