Project documentation with Sculpin

Posted on by Matthias Noback

Recently I've been reading the book Living documentation by Cyrille Martraire. I can warmly recommend this book to you. It basically provides a solution for the age-old problem of creating and maintaining accurate, up-to-date and useful project documentation. One of the key ideas is to generate documentation instead of writing it. This should help prevent duplication and outdated information that is not trust-worthy and would therefore be neglected. I'm currently looking for ways to technically accomplish such a thing with PHP projects. This should result in reusable tools which will make it easier and more fun to document future projects while writing the code.

The first thing I was looking for was some kind of framework for any number of tools that would analyze a project and generate a documentation site for it, consisting of diagrams, texts, maps, etc. All in one place, all easily navigable and searchable. I was immediately reminded of Sculpin, a static site generator created by Beau Simensen. I've used it for years as the engine behind this blog. You could say that this blog is a "Sculpin project", which is the standard way to use Sculpin. However, I wanted to use Sculpin to document another project, the main project.

So I started figuring out how to run Sculpin and generate a static subsite (not a blog) based on files in a subdirectory of another project. It wasn't all that hard, but I'll share the steps here anyway.

Use Sculpin to generate a static website in a subdirectory of your project

Run the following commands in the root of the project you're creating a subsite for. Assuming you have the Composer executable available as composer and your project already has a composer.json file, and the files for your subsite should be located in doc/, run:

composer require sculpin/sculpin
mkdir doc
vendor/bin/sculpin generate --project-dir=doc

Define the homepage for the site by creating a new file: doc/source/index.md. Put some minimal Markdown content in it, to test if it works:

---
title: Home
---

# Documentation for project X

Before the Markdown content you will find the so-called frontmatter which could contain any relevant metadata. The value of the title key will be available later on when rendering the page as the variable page.title.

Now, run:

vendor/bin/sculpin generate --server --project-dir=doc

In your browser, go to localhost:8000, and you should see the homepage (which shows the parsed version of index.md).

From here on, everything is optional and just a suggestion to get started.

Create a new file: app/config/sculpin_site.yml. Now you can configure the title of the site:

# in sculpin_site.yml

title: Documentation for project X

Create a directory doc/source/_layouts. This will contain any layout file for the Twig formatter. Create a default layout in doc/source/_layouts/default.html.twig, something like:


<!DOCTYPE html>
<html>
<head>
    <title>{{ page.title }} &mdash; {{ site.title }}</title>
</head>
<body>
    {% block content %}{% endblock %}
</body>

You need at least a content block for the content from the index.md page to be rendered.

Now modify the frontmatter of index.md (the part that has Yaml-formatted content in it) to look like this:

---
layout: default
title: Home
---

The layout key will cause Sculpin to look for the default.html.twig file.

To preview the generated site, you could run:

vendor/bin/sculpin generate --project-dir=doc --server --watch

Open localhost:8000 again (or refresh the page) and you should see a very simple HTML page (take a look at the page source to find out if the full HTML document has been rendered according to your layout file). The --watch flag is optional and will keep regenerating the site upon file changes (not all of them though; I find myself regularly restarting the server).

Themes

Looking at the doc/ directory you can see that we have only a very small amount of files. It should be no problem at all to copy this basic setup into new projects whenever you need a documentation platform.

The files you may want to reuse are layout files and other template-related files, and static assets. You could easily create a reusable (and overridable) package for this. You only need to create a Composer page of type 'sculpin-theme' for it. Take a look at the Bootstrap 3 theme for more clues on how to accomplish this.

Next up

In a next post I'll share with you an easy way to let Sculpin generate "virtual" pages and assets (which are different from both custom content types and generators).

PHP Sculpin documentation
Comments
This website uses MailComments: you can send your comments to this post by email. Read more about MailComments, including suggestions for writing your comments (in HTML or Markdown).
IceCap

Really interesting...But I didn't get it to work in Symfony 2.8...perhaps are you using Symfony3?

Matthias Noback

Hmm, I used 2.8. Don't know what could go wrong.