ana

I just received a question about how to use Dexy to document procedural (non-OOP) PHP code. Here are some ways of using dexy to document PHP. These examples assume you already have familiarity with the contents of the Getting Started part of the guide.

The contents of the resulting HTML file could also be displayed in HTML documentation using an iframe. This is done a lot in the Getting Started guide.

Sections of Files

To document what is going on in a file, we really need to be able to isolate sections of a file to discuss what is happening in that small section. We can do this using the idio filter in dexy, and fortunately this filter has recently been redone to support HTML-style comments as well as comments used in most programming languages, so you can mix and match these within an embedded PHP file. (You probably noticed these comments in the PHP file above.)

In the dexy.yaml file, we apply the idio filter to our php example file:

-example.php|idio:-idio:{lexer:'php',lexer-args:{startinline:True}}

Then, we can talk about just the head section in the HTML:

<head><title>PHPExample</title></head>

Or the assign-variables section:

$b=$a=5;$a++;

And then the section where we compare the variables:

if($a>$b){echo"<p>a ($a) is bigger than b ($b)</p>";$b=$a;}

Here is the source of how these items were included in this document:

{{d["example.php|idio"]["head"]}}

{{d["example.php|idio"]["assign-variables"]}}

{{d["example.php|idio"]["compare"]}}

HTML-style comments will be preserved as your php passes through the php filter (just be careful to leave a blank line after each closing ?>), so that you can also apply the idio filter to the output from the php filter:

-example.php|php|idio:-idio:{lexer:'html'}

In this way we can show the php:

<?phpecho"The value of a is $a."?>

And the resulting HTML:

The value of a is 6.

Here’s how we included each of these in this document:

{{d["example.php|idio"]["display-variables"]}}

{{d["example.php|php|idio"]["display-variables"]}}

Syntax Highlighting Sections

You might have noticed that the syntax highlighting wasn’t applied to the HTML content in the previous section, and we had to pass some custom arguments to the lexer to make things work for the PHP content. The PHP syntax highlighter in pygments is stateful and keeps track of whether it is in a HTML or PHP region of the source code file. However, because we pass our source code in in sections, the lexer isn’t able to keep track of the state.

This should be a solvable problem and you can track progress on it here, but for now you’ll have to tweak the settings if you want syntax highlighting, and please feel free to get in touch if you need help getting the output you want.

Deployment, Screenshots and Integration Testing

An additional approach which you can take to documenting PHP projects is to start a server locally (or on a virtual machine either locally or in the cloud) and run a headless web browser against that server to take screenshots and make assertions about the displayed content.

This approach is applicable to any web application, regardless of the underlying technology. It also allows you to document JavaScript components of your application. (You can also use the same pyg and idio filters to document JavaScript source files.)

The quickstart section of the Dexy Guide contains an example of bash scripts which start a local server, casper.js scripts which interact with the application running on that server, and then take screenshots and make assertions about the state of the application, as well as documentation which incorporates all these elements.

For example, here is a fully automated full-page screenshot of the polls app from the Django tutorial:

This prints the LaTeX markup in our R session. The Stargazer docs say:

‘stargazer’ uses ‘cat()’ to output LaTeX code for the table. To
allow for further processing of this output, ‘stargazer’ also
returns the same output invisibly as a character string vector.
You can include the produced tables in your paper by inserting
‘stargazer’ output into your publication's TeX source.

So, according to this there’s no built-in way to get stargazer to write its output directly to a file. One option would be to use R’s sink() to divert the output from stargazer:

> sink("output-from-sink.tex")> stargazer(attitude)> sink()

This gives us a file named output-from-sink.tex which we can include in documents.

That works fine, we can create as many separate files as we need. However, it might be nice to create a single file with multiple LaTeX snippets in it, referenced by name.

To do this we create a list and add named elements to the list containing output from running stargazer:

It was pretty late last night when I finished my post about blogging with WordPress and Dexy, so I didn’t even notice it had turned into π day. This morning of course twitter reminded me, and in particular this caught my eye:

Can anyone draw me a plot of √[6(1 + 1/2^2 + 1/3^2 + 1/4^2...)] →π? Excel is not only ok, it’s recommended. Should bounce around and close in.

For a developer, trying to blog about code is a frustrating process. WYSIWYG content editors mangle code and whitespace. Tools like gist and other code-snippet displays can help, but they also distance your code from your writing. With Dexy, we can write blog posts that incorporate code just where we want it, in the format we want it, and with confidence that the code we are writing is correct and easy to modify as we go.

In this tutorial we’ll walk through creating and then modifying a WordPress blog post. All the features mentioned in this blog post are available in Dexy 0.5.7. In order to post content to WordPress we will use its XMLRPC API, so before you try this yourself make sure you have enabled this option; it is disabled by default.