The way the code has developed (basically, a gallop to produce a workable processing system for a series of blog posts) has left a lot of wounded soldiers in its wake. Any function that produces HTML should ideally use jinja templating based on template files, to allow a clean separation of content and presentation as well as multiple representations of the same content.

While the system successfully renders the textual content, embedded hypertext links are not currently handled - mostly because I'm not yet sure how they are handled inside a document. It's quite important to pass these through!

Simple feature request.

We need some way to allow us to extract snippets from the article base in a controlled way.

Ideally it should be able to cope with files of which the snippet is only a part, allowing the snippets to be updated in the article then re-integrated into the base file in Github.

At present much of the code is left over from the "programming with a trowel" phase, and lies around simply acting a a trap to the unwary. this is particularly true of walk_blog.py, which I have now several times modified in the wrong place due to retention of this old functionality (render_* methods, much of it).

Now the code is approaching alpha it should be stripped of such irrelevancies.

The walk_blog.py code was developed with simple HTML production in mind, and it shows. Most function generate their output with print calls, of which there are twelve in the file, direct to standard output.

To make the code more testable, functions that currently print should be modified to instead return the string they currently print, and their callers suitably modified to deal with this new output.

This will also avoid the horrors of output redirection currently involved when one attempts to re-use code (cf. the load function).

At present there is a nascent but (like everything else) undocumented cacheing feature in the project. Given a document's id there are currently three operations you can perform:

• pull <document_id> reads the document through the Google Docs API and saves a copy in the cache as <document_id>.json.
• load <document_id> reads the document from the cache, parses it and produces HTML output in the cache as html/<document_id>.html.
• view <document_id> reads the document from the cache, parses it and sends the HTML output to stdout.

Document ids are not a natural format for human use, so some way of easily being able to find and reference a single document (and, who knows, maybe a collection of them as well) will be needed early in the lifetime of the project.

There are many possible ways to solve this problem. I'm happy to consider any contributions.

This early stage has been reached with an awful lot of bottom-up noodling, from which the vestiges of an API and a processing pipeline have started to emerge. At present there are no virtual environment specifications, and not even any guarantee the the repository contains enough material to reproduce the results shown in the demo 1 video.

It will be helpful for someone with no priori involvement in the project to go through the perhaps slightly painful process of establishing the required changes to allow other developers to participate fairly easily.

At the time of writing the project is only just out of the discovery phase, and the shape of the eventual API is still only just emerging. In particular, output is currently generated in stdout rather than in some more conveniently packaged form, and this should perhaps be remedied before the code is easily testable.

Even so there are some tests that can, and should, be performed (e.g., the element_type function) even with the code in its existing shape. As the code is refactored, progress should be made using TDD rather than the ad hoc methods that have reigned until now.

The project should also have some contributor guidelines, where this advice should apear.

At the moment the software is driven by copying and pasting document Ids, which is acceptable for a proof of concept but absolutely useless for any other kind of productive work.

Given that the system already integrates a web server one possibility is to build a page within it that allows the user to create a new document in Google Docs, registering it in the local database at the same time and thereby making each document a manageable document. It would also be convenient to be able to register existing documents easily through a web interface of some kind.

Some teachers like to publish code in a non-copyable form to encourage students to engage with the code. We might therefore choose to translate code paragraphs into graphics to accommodate this need.