Documentation has moved to GitHub

Open source documentation

Diem documentation is quite complete:
22 Reference Book pages
+7 Diem Ipsum pages
+7 Howto pages
*2 versions (5.0 and 5.1)
= 72 pages

Untill today, only diem-project.org webmasters were able to write and fix Diem documentation. That was a hard time.

So I took some time to move all documentation to GitHub: Diem Documentation GitHub repo. Now you can create documentation issues, and even better, fork and improve it!

Git branches are used to separate 5.0 and 5.1 documentation: 5.0, 5.1.

The best thing is that diem-project.org pages are synchronized with the documentation repository. Each time we push to GitHub, the website is automatically updated, thanks to a post-receive hook.

Synchronize a Git repo with a database

In case you need, as I did, to update a database each time a Git repository receives data, this section may help you.

Install a local repo on the production server

As diem-project.org is itself a Git repo, I added the documentation as a submodule:

git submodule add git://github.com/diem-project/diem-docs.git data/diem-docs  

Configure the GitHub repo

Add a post-receive hook url to the GitHub repo. The url must execute a symfony action on the website.

The symfony action

So this action gets called each time Diem GitHub repo receives data.
We need to fetch the files using Git, then read them to upgrade the database.

// handle GitHub post-receive hook  
  public function executeUpdateFromGit(dmWebRequest $request)  
  {  
    $this->forward404Unless($request->isMethod('post'));  
 
    $repoDir = sfConfig::get('sf_root_dir').'/data/diem-docs';  
 
    // include phpGitRepo  
    require_once(sfConfig::get('sf_root_dir').'/lib/vendor/php-git-repo/lib/phpGitRepo.php');  
 
    // create a git repo instance  
    $repo = new phpGitRepo($repoDir);  
 
    // run the synchronizer passing it the repo instance  
    $synchronizer = new gitDocumentationSynchronizer($repo);  
    $synchronizer->execute();  
 
    return $this->renderText('done');  
  }  

See the action code on diem-project.org GitHub repo

To get new files from the GitHub repo I used php-git-repo, a lightweight PHP abstraction layer to Git.
I create a phpGitRepo instance and pass it to my database-specific synchronizer.

The synchronizer

For each Diem branch (currently 5.0 and 5.1), the synchronizer will checkout the appropriate Git branch and update it from the server using php-git-repo.
Then it compares files to the database content, and updates the database if needed.

class gitDocumentationSynchronizer extends dmConfigurable
{  
  protected $repo;  
 
  public function __construct(phpGitRepo $repo)  
  {  
    $this->repo = $repo;  
  }  
 
  public function execute()  
  {  
    $this->repo->git('fetch origin');  
 
    foreach($this->getBranches() as $branch)  
    {  
      $this->checkoutBranch($branch);  
 
      $this->updateBranch($branch);  
 
      $this->updateDatabase($branch);  
    }  
  }  

See the synchronizer code on diem-project.org GitHub repo

---

If you find a typo on Diem documentation, or wanna see something documented better, feel free to create an issue. Or even better, fork the repository and pull your contribution request.

Happy Dieming and stay tuned, Diem 5.1 is coming along very, very nicely!