1 Introduction
This article describes the use of inspection of Python code It uses the inspect module from the Python standard library. From that inspection, it generates JSON output. Sample code is also included to turn that JSON output in each of the three light-weight markup languages reStructuredText (for Docutils), Asciidoc (for Asciidoc or Asciidoctor), and Markdown.
You can find this sample code here: python_info_extract.zip
2 How to use it
Follow these steps:
For docutils and reStructuredText:
./extract_module_info.py -p -f sample_module01 tmp.json ./format_to_docutils.py -f tmp.json tmp.txt rst2html.py tmp.txt tmp.html elinks tmp.html
For asciidoc:
./extract_module_info.py -p -f sample_module01 tmp.json ./format_to_asciidoc.py -f tmp.json tmp.txt asciidoc tmp.txt
For markdown:
./extract_module_info.py -p -f sample_module01 tmp.json ./format_to_markdown.py -f tmp.json tmp.md markdown_py --file=tmp.html tmp.md elinks tmp.html
There are bash scripts in this project that perform the above transformations on the sample module (sample_module01.py):
- run_test_asciidoc
- run_test_markdown
- run_test_docutils
You can also pipe JSON content from one script to the next. Some examples:
./extract_module_info.py sample_module01 | ./format_to_asciidoc.py - ./extract_module_info.py sample_module01 | ./format_to_markdown.py - ./extract_module_info.py sample_module01 | ./format_to_docutils.py -
There are bash scripts in this project that perform these tasks on the sample module, also:
- run_test_asciidoc_pipe
- run_test_docutils_pipe
- run_test_markdown_pipe
3 What next
These scripts, while functional, are intended as templates to be used and extended. So, for example, you might:
- Extract and add more detailed information to the JSON generated by extract_module_info.py.
- Add more details to the lightweight markup generated by format_to_asciidoc.py or format_to_docutils.py or format_to_markdown.py.