Hi all! I am a web developer primarily, but I feel like this is the right place to talk about my literate programming tool and experiments. For those who are not aware of literate programming, it generates production code ideally and documentation from a single source. Ever since I saw this literate programming talk I have been messing with existing literate programming tools. After trying multiple tools, I ended up writing my own tool using python + sphinx + cog + markdown. I am calling it wheel. It can be used for any programming setup, and it generates html documentation using templates and preprocessors that are commonly used in web development.
1. Wheel - literate programming tool with python + sphinx + cog + markdown + jinja.
2. Plannr (beta) - My App - Evernote + twitter. The Code Walkthrough. I use code generation techniques over hylang and sqlite for the backend.
3. Bitrhythm - my live coding app to make techno. Docs.
Why literate programming ? I bet each one of you has a codebase that you can no longer understand. Literate programming completely fixes this. The other solution I can think of is at the text editor level, like leo, but that doesn't have the advantage of using the web. Apart from free-from documentation - hyperlinks, TODO’s and FIXME’s can greatly enhance everyday development. You can also use cog for simple preprocessing to enable and disable simple feature flags and if you are feeling adventurous for doing code generation with python. Here's a project that uses cog for implementing reflection in C++.
How literate programming can help game developers ? Well for that you need to check out this book on physical rendering that won the 2014 Academy Award for Technical Achievement, written using another literate tool noweb. For games, I think code could be organized around levels and design assets could be directly linked to the pages. For handmade hero in particular, I think literate programming would work well alongside the video tutorials.
At this point, I can't go back to writing normal code. Organizing code by files and folders feels too primitive when you have pages, snippets and hyperlinks. I plan to move all my projects to using literate programming in the future. My next project is to develop a small animation tool using three.js. If you guys have a working codebase that you would like to port to literate programming, I would love to try it, but I will need your help.
Link of my 3D animation tool - Virtuator, currently in active development. I want to mention that a literate document can also function as a Game design document. By treating each chapter as a feature, you can document all major design decisions, research and bugs in detail ... which helps a lot in onboarding any programmer/designer/stakeholder to the project.