c2rst.py 2.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. #!/usr/bin/env python
  2. # This Source Code Form is subject to the terms of the Mozilla Public
  3. # License, v. 2.0. If a copy of the MPL was not distributed with this
  4. # file, You can obtain one at http://mozilla.org/MPL/2.0/.
  5. import sys
  6. import re
  7. # Converts a header file to restructured text documentation
  8. #
  9. # All text in /** */ comments becomes restructured text. Everything else is
  10. # included as a code-block with C syntax highlighting.
  11. #
  12. # The beginning and end of the header are removed.
  13. # - Find the first /** */ comment -> start of the documentation
  14. # - Find the last line beginning with "#ifdef" -> end of the documentation
  15. remove_keyword = [" UA_EXPORT", " UA_FUNC_ATTR_WARN_UNUSED_RESULT",
  16. " UA_FUNC_ATTR_MALLOC", " UA_RESTRICT "]
  17. def clean_comment(line):
  18. m = re.search("^\s*(\* |/\*\* )(.*?)( \*/)?$", line)
  19. if not m:
  20. return "\n"
  21. return m.group(2) + "\n"
  22. def clean_line(line):
  23. for keyword in remove_keyword:
  24. line = line.replace(keyword, "")
  25. return line
  26. def comment_start(line):
  27. m = re.search("^\s*/\*\*[ \n]", line)
  28. if not m:
  29. return False
  30. return True
  31. def comment_end(line):
  32. m = re.search(" \*/$", line)
  33. if not m:
  34. return False
  35. return True
  36. def first_line(c):
  37. "Searches for the first comment"
  38. for i in range(len(c)):
  39. if comment_start(c[i]):
  40. return i
  41. return -1
  42. def last_line(c):
  43. "Searches for the latest ifdef (closing the include guard)"
  44. last = 1
  45. for i in range(len(c)-1,1,-1):
  46. m = re.search("^#ifdef", c[i])
  47. if m:
  48. last = i
  49. break
  50. # skip empty lines at the end
  51. for i in range(last-1,1,-1):
  52. if len(c[i].strip()) > 0:
  53. return i
  54. return len(c)-1
  55. if len(sys.argv) < 2:
  56. print("Usage: python c2rst.py input.c/h output.rst")
  57. exit(0)
  58. with open(sys.argv[1]) as f:
  59. c = f.readlines()
  60. with open(sys.argv[2], 'w') as rst:
  61. in_doc = False
  62. last = last_line(c)
  63. for i in range(first_line(c), last+1):
  64. line = c[i]
  65. doc_start = False
  66. doc_end = False
  67. if in_doc:
  68. doc_end = comment_end(line)
  69. line = clean_comment(line)
  70. else:
  71. doc_start = comment_start(line)
  72. if doc_start:
  73. doc_end = comment_end(line)
  74. line = clean_comment(line)
  75. if doc_start:
  76. in_doc = True
  77. if not ((doc_start or doc_end) and line == "\n"):
  78. if not in_doc:
  79. line = " " + line
  80. rst.write(clean_line(line))
  81. if doc_end and i < last:
  82. rst.write("\n.. code-block:: c\n\n")
  83. in_doc = False