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.