Looking for more information on how to do PHP the right way? Check out PHP: The Right Way

SitePoint PHP Blog:
Using Sphinx for PHP Project Documentation
Aug 17, 2015 @ 09:19:04

The SitePoint PHP blog has posted a guide to using Sphinx, a documentation generation tool that's used behind the scenes for the ReadTheDocs hosted documentation service.

I recently had the need to write proper prose-like source-code documentation for the Diffbot PHP client. Having looked at several documentation generators, and even having suggested a @prose tag for importing of related MD/reST documents into method and class descriptions, I realized there simply is no perfect solution we can all agree on (yet). So until I extend Sage with a @prose token and reST parsing, I opted for ReadTheDocs and Sphinx.

He starts with a quick "TL;DR" of the necessary commands to get things working quickly but follows it with the full details. He walks you through the installation of Sphinx locally, setting up the folders and adding a custom theme. He show how to create the table of contents, activate the PHP syntax highlighting and how to show/hide the "Edit on GitHub" links. He also includes the steps to convert Markdown documents into the reST format and, finally, adding the project to the ReadTheDocs site and pushing your results.

tagged: sphinx project documentation tutorial readthedocs markdown rest

Link: http://www.sitepoint.com/using-sphinx-for-php-project-documentation/

SitePoint PHP Blog:
Building a Micro Markdown API App with Lumen
May 12, 2015 @ 10:35:57

The SitePoint PHP blog has a new tutorial posted showing you how to create a small API service with Lumen, the recently released microframework from the creators of Laravel. Their example service takes in Markdown content and translates it to be returned as JSON.

If you’ve been using Laravel for a while, you know that it sometimes feels a little heavy for a small application or service. For that same purpose, Taylor, the creator of Laravel built Lumen. A small micro-framework built on top of Laravel Illuminate components, it doesn’t load all the components by default like Eloquent, Blade, Middleware, etc, remaining light as it boots up. We will explore all of that this short tutorial. [...] To illustrate a practical use case for the micro framework, we will be creating a Markdown parser API application where the user can submit a Markdown text and get back the parsed content as JSON. I will be using the league/commonmark package from the PHP League.

They walk you through the installation of a Lumen instance (via Composer) and how to build out the folder structure for things like resources, database configuration and views. They then include the code for the route and controller to take in the Markdown content and translate it out to HTML as a first step. Then they use the same functionality and return the HTML result as a JSON document. Also included is a simple few line call with Guzzle to the API to pass in a Markdown file and fetch the result.

tagged: tutorial markdown lumen microframework commonmark translate api microservice

Link: http://www.sitepoint.com/building-micro-markdown-api-app-lumen/

Paul Jones:
Bookdown: DocBook-Like HTML Output From Markdown
Mar 05, 2015 @ 10:49:27

Paul Jones has posted about a new tool he's worked up specifically for authors looking to write using Markdown and wanting it to generate out like DocBook results. His tool, Bookdown, uses Markdown and JSON files instead of XML configurations.

Yes, I know, there’s a ton of static site generators for PHP out there already [...but they're] not DocBook-like documentation. By “DocBook-like”, I mean (among other things) numbered headers, auto-generated tables-of-contents on their own pages, hierarchical multi-page presentation, and the next/previous/up linking at the top and bottom of pages.

[...] So: Bookdown. This scratches my particular itch, with very few dependencies. Bookdown, although it can be used as a site generator, is only incidentally a site generator. What it really is is a page generator, with the idea that you can integrate the pages into any other site you want.

The library is separate from the project and is written to use a dependency injection methodology to keep things decoupled and well-structured. If this sounds interesting either for personal use or if you'd like to check out the code, head over to the project site for more information.

tagged: markdown bookdown library project docbook output static generator

Link: http://paul-m-jones.com/archives/6088

Developer Drive:
Simplify your documentation process with Couscous
Dec 19, 2014 @ 12:14:49

On the Developer Drive site today there's a quick post introducing you to Couscous, a PHP-based documentation generation tool. Couscous translates your Markdown files into HTML output that's professional and clean looking.

If there’s one thing I hate more than tracking down bugs, it’s documenting code. It takes forever, it’s almost a project in itself, and I never seem to factor it into my project lifecycle. Setting out to solve that problem for me, and anyone else whose life is too short, is Couscous. Couscous takes markdown files and converts them into professional standard HTML docs that colleagues, or fellow developers, can easily follow. You can preview the resulting site on your local machine, correct any issues, and then deploy straight to GitHub where it will be hosted for you.

They walk you through the (brief) process of getting the tool installed via Composer and using it to show you a preview of your documentation. The "deploy" command then allows you to easily deploy the results out to a GitHub Pages location on the gh-pages branch. You can find out more about Couscous on the project website.

tagged: documentation couscous tool markdown generate html output

Link: http://www.developerdrive.com/2014/12/simplify-your-documentation-process-with-couscous/

Statamic 101
Dec 11, 2013 @ 10:40:41

NetTuts.com has a new tutorial posted today introducing you to Statamic, a PHP-based content management system that uses flat-files instead of database entries to manage its content. (One note, Statamic is not free software and there's no "trial" version)

Statamic is a modern PHP CMS which really makes an effort to be easy and intuitive to use. From its flat-file design to its use of technologies, like markdown and Yaml, you can accomplish an outstanding amount of work without writing any code at all. In this article we will take a look at the process from installation to setting up a basic portfolio.

The CMS (downloadable here) has a simpler structure than some other systems as most of the content is just files in the "_content" directory. They talk some about the directory structure of the tool and help you get things configured via the main YAML config. The post then moves on to working with themes and how to get dynamic content in a basic layout. From there they go on to talk about making new content, adding entries and various other topics like administration and templating.

tagged: statamic cms introduction file markdown template layout content

Link: http://net.tutsplus.com/tutorials/php/statamic-101

SitePoint PHP Blog:
Using PHP Streams Effectively
Nov 21, 2013 @ 11:54:02

Vito Tardia has a new tutorial posted to the SitePoint PHP blog today showing you how to use PHP streams effectively, a continuation of his streams series started here.

n my previous article we've discovered the basics of PHP Streams and how powerful they were. In this tutorial we are going to use this power in the real world. First I'll show you how to build your custom filters and attach them to a stream, then we'll package our filters inside a document parser application.

He starts out by introducing the concept of filters in streams - bits of code that can be attached to the stream to perform operations on the data traveling through it. He includes a simple base64 encoding example with a fopen call to illustrate. He gets into more complex filtering by creating a Markdown filter capable of translating the incoming Markdown-formatted data into a document using the MarkdownExtra library. He also includes an example of another filter added on post-Markdown conversion, a Template filter using the RainTPL templating library.

tagged: using streams filter markdown template tutorial

Link: http://www.sitepoint.com/using-php-streams-effectively/

Hannes Magnusson:
New PHP.net designs floating around
Sep 06, 2013 @ 11:50:37

In a new post to his site Hannes Magnusson talks some about the current PHP documentation (and PHP.net site) formatting and how, while changes to it are quick, they should be instant. He suggests a path to get there and a new tool that could help.

Since 2008 there have been numerous efforts to create a new design for www.php.net, all of which have failed - so far. We've never come as close as two years ago, when the "beta mode" option was added to our website, but we never really got around to finish it. The "beta design" has even received a lot of makeover compared to what is "beta mode" now. To make things a little bit more awesome, there is also a new branch called "responsive" which has a lot of changes in it too, especially for manual pages. Hopefully, one day, we'll actually finish one of these and flip the switch forever.

While he's been a fan of the DocBook structure that's currently in use, he points out that learning the markup can be a hinderance to people contributing. His tool, PhD, does some custom parsing too adding additional complexity. To help, he's working on a new tool (WTFM) to use Markdown formatting instead of DocBook, a more common format.

tagged: phpnet website design docbook markdown update

Link: http://bjori.blogspot.com/2013/09/new-phpnet-designs-floating-around.html

Building ePub with PHP and Markdown
Mar 04, 2013 @ 10:52:45

On PHPMaster.com today there's a new post showing you how to create ePub documents from Markdown-formatted files with the help of the md2epub and RainTPL libraries.

The ePub format is a publishing standard built on top of XHTML, CSS, XML and more. And since PHP is well suited for working with HTML and friends, why not use it to build ebooks? In this article we’ll see what goes into building a tool for creating ePub packages starting from a set of content files. Maybe it’s your next best selling cyber-sci-fi novel or documentation for your latest code project… because we all write good documentation for our projects, don’t we?

He starts off with an introduction to the ePub format, showing the directory structure the package has to follow and some example contents. He helps you set up a test book with two chapters, cover images, styling and a cover/title page. Included in the tutorial is all of the code you'll need to make your own "ePub builder" tool and a suggestion of a tool to check the end result.

tagged: tutorial epub markdown mb2epub introduction


A Quick Look at Sparks
Mar 14, 2012 @ 09:49:36

On CodeIgniter.com there's a new post looking at Sparks, reusable code components/packages for the CodeIgniter framework.

On the back of a CIConf in London last month, I would like to delve a little into a common theme amongst CodeIgniter developers. Speeding up development through simple automation. To do that we’re going to take a look at the CodeIgniter Sparks project and how it can drastically speed up your development. To demonstrate, I will walk through building a little portfolio that leeches off the GitHub API.

They show you how to install it from the Getsparks website, finding Sparks to add to your application, the code to load in the component and configuring it on load. They include an example of loading in a REST client Spark and how to use it to make a request to Github and pull down a Markdown file.

tagged: sparks package install tutorial rest markdown


Anna Filina's Blog:
Integrating Markdown with Symfony
Apr 26, 2011 @ 10:56:46

Anna Filina has a new post showing how you can integrate a documentation format that's become a bit more popular recently (due partially to its increased use on github), Markdown, into a Symfony application.

I needed to create a number of static help pages in three languages in a Symfony 1.4 application. Using the XLIFF translation files seemed absurd, since I knew that I will include a lot of HTML. [...] And so, I decided to create partials using the following structure: _docs/{lang}/{title}.php. This method would organize my pages nicely and will only load what is needed. Then, I remembered that we were planning to hire a technical writer for the rest of the manual. I wanted to make his life as easy as possible and the source files easy to read for everyone.

She found the solution in Markdown and has included a step-by-step guide to getting it integrated with Symfony using this parser. It's loaded as a helper and used to parse the partial view's content. You can find a quick guide to Markdown on the Daring Fireball website.

tagged: markdown symfony framework helper view