buroca 0.1.10

A framework to help implementing Bureaucracy as code.

“Buroca” is a Python command line tool that helps implementing a “bureaucracy as code” philosophy of project management. It was created to help creating documents for a partnership project between a public University and the Federal Goverment in Brazil, – a case that we can certainly expect lots of pointless paperwork. Buroca can also help with other workflows that involves automatic generation of documents.

A “buroca” project keeps a centralized data store and a set of document templates. It fills the gaps by providing automatic document generation and easy synchronization of generated documents with the data store. Buroca understands arbitrary text files (e.g: markdown, LaTeX, etc) and LibreOffice spreadsheets.

Installation

Buroca requires Python 3 and a few other libraries available on pip. You can grab it from pip:

$ pip3 install buroca --user

More advanced usage requires pandoc <http://pandoc.org> and an working instance of LibreOffice. It probably works only on Linux, but you’re welcome to contribute Windows support ;).

Usage

Start creating by a project folder structure:

$ buroca init

It will create the following folder structure in the current directory:

data/
reports/
templates/

Data must contain a set of YAML files that encode information about each entity in your project. You can create arbitrary YAML files representing people, inventory, reports or anything you want.

A fairly common usage is to include a person/ sub-folder with one file per person:

data/
 |- band.yml           -- generic project information
 \- person             -- we create one YAML file per member of the
     |- john.yml          project
     |- paul.yml
     |- ringo.yml
     \- george.yml

The content of those files is arbitrary, as long as they encode dictionaries:

# john.yml
name: John Winston Lennon
role: singer
instruments:
    - guitar
    - keyboard
    - harmonica
    - tambourine

Now, we must create some template documents in the “templates” folder. They can be either arbitrary text files or Libre Office spreadsheets. Those files are interpreted as Jinja2 <http://jinja.pocoo.org> templates. The toplevel files and folders are exposed as variables in the Jinja templates.

Consider a templates/resumee.md file:

# Resumée

Name: {{ person.name }}

{{ person.name }} is the {{ person.role }} of {{ band.name }}. He can play
{% for instrument in person.instruments %}{{ instrument }}
{%- if not loop.last %}, {% endif %}{% endfor %}.

{{ person.name }} used to play on {{ band.name }}, the greatest rock band
in history!

Now that we have a template, we can generate files from YAML data:

$ buroca do resumee.md person/john

This will create a resume-john.md file under “reports/” that inserts all information in the YAML files into the correct places. If we want to generate files for all members at once, just type:

$ buroca do resumee.md person/*

It will scan all files like data/person/*.yml and create a report for each person.

Export to PDF

Buroca integrates with pandoc <http://pandoc.org> and can convert several input files to pdf. This is particularly useful to aggregate reports for different entities into a single file. This is useful, for instance, when you want to send files for printing:

$ buroca do resumee.md person/* -t pdf --single

What about this name?

“Buroca” is the informal way Brazillians calls “bureaucracy”. Pointless bureacracy is so prevalent in Brazillian life that we have to invent cute names to better cope with it ;)