Blog

_{Title photo by Pereanu Sebastian}

We are happy to announce that the first chapters of the developer documentation has been deployed on readthedocs.io. You can find it at https://basx-bread.readthedocs.io/. Be aware this is still work in progress and we are nowhere near completion. There is enough documentation to get started though and we will continue to add more topics and examples.

That’s it about the documentation, now let’s talk about the fun part 😉

Sphinx

Since readthedocs is a place-to-go for the documentation of many Python projects we decided to give it a try. The results are very satisfying. readthedocs integrates seamlessly with Github repositories, the build configuration is rather easy to set up and, very importantly, Sphinx is used for generating the documentation. In case you are not familiar with Sphinx for technical documentation, I strongly recommend you to take a look at it and maybe give it a try in your next project. Sphinx uses reStructuredText by default which might feel a bit uncomfortable to use when writing the first few paragraphs, since many of us developers are used to writing in Markdown. However, the Python documentation ecosystem largely evolves around docutils, which is the original implementation of reStructuredText. Things like docstrings in Python therefore tend to be written in reStructuredText and as a Python programmer you might as well give it a chance. But even if you really want to stick with Markdown there is a Sphinx plugin which lets you do that (Sphinx has a ton of other useful plugins which add functionality and new themes). As far as I could see Spinx has also a fair share of users outside of the Python community. Which doesn’t surprise me. Sphinx is an amazing tool! It feels like it has been designed with the attitude that good documentation is not written by authors but by developers. Let me get into the details here:

• Sphinx uses a powerfull but still easy-to-learn markup language
  As already mentioned Sphinx uses the reStructuredText markup language and can be extended to use other languages. Markup languages give us much more consistency and flexibility than traditional WYSIWYG editors like Word. And if you have ever written something in LaTeX then you will also find it a relieve that you do not need to have a Ph. D. (pun intended) to write some piece of content. In some ways I would say Sphinx is to developers what LaTeX is to authors.
• Sphinx is built on plain-text files
  This is maybe a less obvious but still crucial point. First it integrates very well with version control systems. I would say this is a must for documentation of software, you want the documentation to be built with the same version as the code, you want revisions and changelogs and you want to keep the documentation close to the code it is related to. Also, when using the same VCS as the code you do not need waste any “where-should-I-now-just-store-this-file-to-share-it” thoughts. Another big plus for plain-text files is that it does not have any requirements regarding IDE, tooling or software packages (apart from a plain-text editor of course). As developers most of us have their preferred development environment and fine-tuned text editors (VIM for the win!). Being able to integrate Sphinx into any existing workflow is therefore a big plus. The last thing I want to point out here is that having multiple files allows for a developer-way of modularizing content. We use directories and files all the time to structure our code. Having the same option when writing documentation allows to think and organize the same way. We do not think in terms of headings and levels but in terms of modularized units.
• Sphinx has nice themes
  There are a couple of theme plugins out there which only require a pip install themename and an entry in the Sphinx configuration file. On of the very common ones is the readthedocs-theme (yes, they wrote their own theme). This point might strike one as less important to a good documentation system. Still, accessibility of the documentation is certainly crucial and an essential part of a theme. Things like navigation, accessing indices and glossaries and searching for content all depend on the layout and format of the generated documentation. I am nowhere near a UI or UX expert but colors, contrast and site structure do have an impact on the readability of a document, especially on technical ones. And the readthedocs themes for example does a great job in implementing the right design there. I always find it a joy to discover that a particular project is documented with Sphinx and the readthedocs theme.
• Sphinx makes referencing very easy
  Referencing other parts of the documentation or even parts of other projects is obviously an important part of a documentation system. Let me give you a few examples:
  – Reference to a function in an internal Python module: :py:func:`bread.utils.urls.default_model_path
  – Reference to a Django module: :py:mod:`django:django.db.models` (in order for reference external projects an entry to the Sphinx configuration needs to be added)
  – Reference a section on the same page: `Section Title`_
  It is of course also possible to define explicit reference targets anywhere in the documentation, using footnotes, citations and more. You can find all the details here. Now, I think referencing on itself is not an easy topic and it needs to thought through. But a large documentation with well written references (e.g. the Django documentation) makes browsing the documentation a very pleasant experience. And Sphinx allows us to do that by trying to get out of the way with its cross-referencing system.
• Sphinx documentation can be published easily and free on readthedocs.io
  This is especially interesting for open source projects or public documentation in general. The only job of readthedocs.io is to publish Sphinx documentation and it does its job very well. Set up a free account, add a project from Github and add a short configuration file to your git repository. That’s it, your done and you never need to think again about publishing workflows and building things. Just work on the documentation, either locally or directly in the Github editor and push your changes. And just like that your documentation is published with the most recent changes. “Fixing typos made ease” 😉

What’s next

Apart from completing the documentation, doing some necessary refactoring and finding and fixing bugs we are also working on a next extension of the framework. So far we only have a single extension for generating reports. While we are planing to extend the features and usability of the reports extension in the future, we are having a more pressing requirement for implementing some kind of workflow engine. In a recent meeting we discussed a few approaches on how to do that. While personally I would at first think mostly in terms of dependency graphs, it turned out that having an approach which support requirements engineering and client communication would make a workflow engine much more useful. Two formal methods of defining workflows were dominant in our discussion: UML Activity Diagrams and BPML (Business Process Modeling Language). For a couple of reasons we decided to go with UML Activity Diagrams (some of them were tooling availability, familiarity and undesirable affinity with “business-only-tools”).

What this means is that we will write an API to declare Activity Diagrams in code. These diagram definitions will be made available on the front-end to let a user start a workflow. Workflows can contain actions which might require user input as well as automated actions and decisions. I think in real-world use cases we can expect the generated diagrams to look a bit more verbose than standard UML Activity Diagrams. Due to the necessity of mapping to a database system and in order to prevent ambiguity the implementation of these workflows will require a good degree of details. I am already experimenting with the first implementations and I think I am well underway with the API and the data model but still have some question marks on how exactly to integrate things into the user interface. But that is for another post I guess.