Hello,
I am interested in tools similar to librustdoc (https://github.com/rust-lang/rust/tree/master/src/librustdoc), which can include executable tests into product documentation. For example, find a text box with the Play button at https://doc.rust-lang.org/rustdoc/documentation-tests.html. In particular, I would like to have such a tool to document a software app writen in Python.
Thanks,
Alex
2 Likes
The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text. Uses include: data cleaning and transformation, numerical simulation, statistical modeling, data visualization, machine learning, and much more.
Thanks, interesting. I have used Jupyter but I haven’t generated Jupyter notebooks as documentation. Or I could just try writing documentation with the app imported. (Not sure if developing the app in Jupyter would work for me.)
The approach is called Literate Programming. It is introduced by Donald Knuth. Maybe this can help you narrow the search.
Another great tool for literate programming is babel + orgmode in Emacs. You can write a snippets of code in any language supported by Emacs and mix it with orgmode markup narrative. Being an Emacs package it has a steeper learning curve but is very powerful and flexible.
BTW, for Python you can take a look at doctest which is a Python standard testing approach using docstrings. Coupled with a tool that can extract docstring (I think Sphinx can do it) might achieve what you want.
1 Like
I know for LP, used it in take-home projects in grad school around 1995. I can’t write only in Jupyter but I will definitely make use of it for some aspects.
Thanks
1 Like