1

Is there some tool (preferably in Python) that allows you to generate reports in HTML, Markdown or reStructuredText from arbitrary source code (Python, R, Javascript, etc)?

The closest thing I have found so far is pyreport that only supports python. The idea is to be able to get a quick report from well-documented source code. This is different from literate programming; here I want something similar to the following:

file.py

# ```*This is part of a comment*
# maybe some equations $c^2=a^2+b^2$ or [links](http://mylink.com) here ```
def calculate_something():
    print(42)
calculate_something()

and the report should be something like this:

This is part of a comment

maybe some equations $c^2=a^2+b^2$ or links here

42

This is very similar to documentation generator tools but I need them to work across language, and most (if not all) are language-specific.

Community
  • 1
  • 1
r_31415
  • 8,752
  • 17
  • 74
  • 121
  • 1
    Downvoter, please tell me what is wrong with this question. Otherwise, I can't improve it. – r_31415 Oct 09 '15 at 23:05
  • One question: hat `42` in the expected output, implies that, besides extracting comments, the code should be run? I can't think of any tool that will do that, because the code could be a module, or a program that expects some input... Can you clarify what the tool should use as input (file.py?) and how do you expect the tool to interleave comments with executed code? – jjmontes Oct 17 '15 at 13:27
  • Thanks. Ideally, the tool would be able to extract code that should be run, but the user is expected to provide a way to run it. Yes, the tool would use `file.py` (in the example above) as input. I'm not sure I understand your last question. Do you mean how should the tool work to produce the final report? By the way, I think there are some scenarios in which such a tool wouldn't be so useful (e.g. when your code can't be described sequentially using its comments) – r_31415 Oct 17 '15 at 16:14
  • Why don't you simply add `print` statements in addition to comments? – jjmontes Oct 17 '15 at 16:38
  • Oh, because I wanted to integrate something like this in a feature to generate HTML reports automatically. – r_31415 Oct 17 '15 at 19:20

1 Answers1

1

Can you maybe use one of the tools listed on the Python Wiki for Source Code documentation, which normally extracts the structure from your code, and includes your docblocks in the documentation.

https://wiki.python.org/moin/DocumentationTools

Steven Scott
  • 10,234
  • 9
  • 69
  • 117