build_rest.py 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379
  1. #!/usr/bin/env python3
  2. """
  3. Created on Thu Aug 9 14:04:12 2012
  4. @author: lucadelu
  5. """
  6. # utilities for generating REST indices
  7. # utilities for generating HTML indices
  8. # (c) 2003-2021 by the GRASS Development Team, Markus Neteler, Glynn Clements, Luca Delucchi
  9. import sys
  10. import os
  11. import string
  12. ## TODO: better fix this in include/Make/Rest.make, see bug RT #5361
  13. # exclude following list of modules from help index:
  14. exclude_mods = [
  15. "i.find",
  16. "r.watershed.ram",
  17. "r.watershed.seg",
  18. "v.topo.check",
  19. "helptext.html",
  20. ]
  21. # these modules don't use G_parser()
  22. desc_override = {
  23. "g.parser": "Provides automated parser, GUI, and help support for GRASS scipts.",
  24. "r.li.daemon": "Support module for r.li landscape index calculations.",
  25. }
  26. ############################################################################
  27. header2_tmpl = string.Template(
  28. r"""
  29. ==================================================================
  30. GRASS GIS ${grass_version} Reference Manual
  31. ==================================================================
  32. .. figure:: grass_logo.png
  33. :align: center
  34. :alt: GRASS logo
  35. GRASS GIS ${grass_version} Reference Manual
  36. --------------------------------------------------------------------
  37. **Geographic Resources Analysis Support System**, commonly
  38. referred to as `GRASS GIS <https://grass.osgeo.org>`_, is a `Geographic
  39. Information System <https://en.wikipedia.org/wiki/Geographic_information_system>`_
  40. (GIS) used for geospatial data management and analysis, image processing,
  41. graphics/maps production, spatial modeling, and visualization. GRASS is
  42. currently used in academic and commercial settings around the world, as
  43. well as by many governmental agencies and environmental consulting companies.
  44. This reference manual details the use of modules distributed with
  45. Geographic Resources Analysis Support System (GRASS), an open source
  46. (`GNU GPLed <https://www.gnu.org/licenses/gpl.html>`_), image
  47. processing and geographic information system (GIS).
  48. """
  49. )
  50. overview_tmpl = string.Template(
  51. r"""
  52. Quick Introduction
  53. ~~~~~~~~~~~~~~~~~~~~
  54. .. toctree::
  55. :maxdepth: 1
  56. How to start with GRASS <helptext.html>
  57. Intro projections and spatial transformations <projectionintro>
  58. Intro 2D raster map processing <rasterintro>
  59. Intro 3D raster map (voxel) processing <raster3dintro>
  60. Intro image processing <imageryintro>
  61. Intro vector map processing and network analysis <vectorintro>
  62. Intro database management <databaseintro>
  63. Intro temporal data processing <temporalintro>
  64. Display/Graphical User Interfaces
  65. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  66. .. toctree::
  67. :maxdepth: 1
  68. wxGUI wxPython-based GUI frontend <wxGUI>
  69. Display commands manual <display>
  70. Display drivers <displaydrivers>
  71. nviz 3D visualization and animation tool <wxGUI.Nviz>
  72. Raster and 3D raster processing
  73. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74. .. toctree::
  75. :maxdepth: 1
  76. Raster commands manual <raster>
  77. 3D raster (voxel) commands manual <raster3D>
  78. Image processing
  79. ~~~~~~~~~~~~~~~~~~
  80. .. toctree::
  81. :maxdepth: 1
  82. Imagery commands manual <imagery>
  83. Vector processing
  84. ~~~~~~~~~~~~~~~~~~
  85. .. toctree::
  86. :maxdepth: 1
  87. Vector commands manual <vector>
  88. GRASS ASCII vector format specification <vectorascii>
  89. Database
  90. ~~~~~~~~~
  91. .. toctree::
  92. :maxdepth: 1
  93. SQL support in GRASS GIS <sql>
  94. Database commands manual <database>
  95. General
  96. ~~~~~~~~~
  97. .. toctree::
  98. :maxdepth: 1
  99. GRASS startup manual page <grass7>
  100. General commands manual <general>
  101. Miscellaneous & Variables
  102. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  103. .. toctree::
  104. :maxdepth: 1
  105. Miscellaneous commands manual <miscellaneous>
  106. GRASS variables and environment variables <variables>
  107. Temporal processing
  108. ~~~~~~~~~~~~~~~~~~~~
  109. .. toctree::
  110. :maxdepth: 1
  111. Temporal commands manual <temporal>
  112. Printing
  113. ~~~~~~~~~~~~
  114. .. toctree::
  115. :maxdepth: 1
  116. PostScript commands manual <postscript>
  117. """
  118. )
  119. # TODO add copyright symbol
  120. footer_tmpl = string.Template(
  121. r"""
  122. --------------
  123. :doc:`Manual main page <index>` \| :doc:`Full Index <full_index>`
  124. 2003-2021 `GRASS Development Team <https://grass.osgeo.org>`_, GRASS GIS ${grass_version} Reference Manual
  125. """
  126. )
  127. cmd1_tmpl = string.Template(r"""*`$cmd.\* <${cmd}>` *""")
  128. cmd2_tmpl = string.Template(
  129. r"""
  130. ${cmd}.* commands:
  131. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  132. .. toctree::
  133. :maxdepth: 1
  134. """
  135. )
  136. desc1_tmpl = string.Template(
  137. r""" ${basename} - ${desc} <${basename}>
  138. """
  139. )
  140. sections = r"""
  141. +-----------------------------+-------------------------------+
  142. |`d.* <full_index.html#d>`_ | `display commands` |
  143. +-----------------------------+-------------------------------+
  144. |`db.* <full_index.html#db>`_ | `database commands` |
  145. +-----------------------------+-------------------------------+
  146. |`g.* <full_index.html#g>`_ | `general commands` |
  147. +-----------------------------+-------------------------------+
  148. |`i.* <full_index.html#i>`_ | `imagery commands` |
  149. +-----------------------------+-------------------------------+
  150. |`m.* <full_index.html#m>`_ | `miscellaneous commands` |
  151. +-----------------------------+-------------------------------+
  152. |`ps.* <full_index.html#ps>`_ | `postscript commands` |
  153. +-----------------------------+-------------------------------+
  154. |`r.* <full_index.html#r>`_ | `raster commands` |
  155. +-----------------------------+-------------------------------+
  156. |`r3.* <full_index.html#r3>`_ | `raster3D commands` |
  157. +-----------------------------+-------------------------------+
  158. |`t.* <full_index.html#t>`_ | `temporal commands` |
  159. +-----------------------------+-------------------------------+
  160. |`v.* <full_index.html#v>`_ | `vector commands` |
  161. +-----------------------------+-------------------------------+
  162. |`nviz <wxGUI.Nviz.html>`_ | `visualization suite` |
  163. +-----------------------------+-------------------------------+
  164. |`wxGUI <wxGUI.html>`_ | `wxPython-based GUI frontend` |
  165. +-----------------------------+-------------------------------+
  166. """
  167. modclass_intro_tmpl = string.Template(
  168. r"""Go to :doc:`${modclass} introduction <${modclass_lower}intro>`
  169. """
  170. )
  171. # "
  172. modclass_tmpl = string.Template(
  173. r"""Go :doc:`back to help overview<index>`
  174. **${modclass} commands:**
  175. .. toctree::
  176. :maxdepth: 1
  177. """
  178. )
  179. # "
  180. desc2_tmpl = string.Template(
  181. r""" ${basename} - ${desc} <${basename}>
  182. """
  183. )
  184. # "
  185. full_index_header = r"""Go :doc:`back to help overview<index>`
  186. Full command index:
  187. ~~~~~~~~~~~~~~~~~~~~
  188. """
  189. # "
  190. message_tmpl = string.Template(
  191. r"""Generated HTML docs in ${rest_dir}/index.txt
  192. ----------------------------------------------------------------------
  193. Following modules are missing the 'modulename.txt' file in src code:
  194. """
  195. )
  196. def check_for_desc_override(basename):
  197. return desc_override.get(basename)
  198. def read_file(name):
  199. f = open(name, "r")
  200. s = f.read()
  201. f.close()
  202. return s
  203. def write_file(name, contents):
  204. f = open(name, "w")
  205. f.write(contents)
  206. f.close()
  207. def try_mkdir(path):
  208. try:
  209. os.mkdir(path)
  210. except OSError as e:
  211. pass
  212. def replace_file(name):
  213. temp = name + ".tmp"
  214. if (
  215. os.path.exists(name)
  216. and os.path.exists(temp)
  217. and read_file(name) == read_file(temp)
  218. ):
  219. os.remove(temp)
  220. else:
  221. try:
  222. os.remove(name)
  223. except OSError as e:
  224. pass
  225. os.rename(temp, name)
  226. def copy_file(src, dst):
  227. write_file(dst, read_file(src))
  228. def rest_files(cls=None):
  229. for cmd in sorted(os.listdir(rest_dir)):
  230. if (
  231. cmd.endswith(".txt")
  232. and (cls in [None, "*"] or cmd.startswith(cls + "."))
  233. and (cls != "*" or len(cmd.split(".")) >= 3)
  234. and cmd not in ["full_index.txt", "index.txt"]
  235. and cmd not in exclude_mods
  236. and not cmd.startswith("wxGUI.")
  237. ):
  238. yield cmd
  239. def write_rest_header(f, title, ismain=False):
  240. f.write(header2_tmpl.substitute(grass_version=grass_version))
  241. def write_rest_cmd_overview(f):
  242. box_color = "#e1ecd0"
  243. f.write(overview_tmpl.substitute(box_color=box_color))
  244. def write_rest_footer(f, index_url):
  245. f.write(footer_tmpl.substitute(grass_version=grass_version, index_url=index_url))
  246. def get_desc(cmd):
  247. f = open(cmd, "r")
  248. while True:
  249. line = f.readline()
  250. if not line:
  251. return ""
  252. if "NAME" in line:
  253. break
  254. while True:
  255. line = f.readline()
  256. if not line:
  257. return ""
  258. if "SYNOPSIS" in line:
  259. break
  260. if "*" in line:
  261. sp = line.split("-", 1)
  262. if len(sp) > 1:
  263. return sp[1].strip()
  264. else:
  265. return None
  266. return ""
  267. ############################################################################
  268. arch_dist_dir = os.environ["ARCH_DISTDIR"]
  269. rest_dir = os.path.join(arch_dist_dir, "docs", "rest")
  270. gisbase = os.environ["GISBASE"]
  271. ver = read_file(os.path.join(gisbase, "etc", "VERSIONNUMBER"))
  272. try:
  273. grass_version = ver.split()[0].strip()
  274. except IndexError:
  275. grass_version = ver.split().strip()
  276. ############################################################################