comodojo/dispatcher.servicebundle.gitdoc

This package is not installable via Composer 1.x, please make sure you upgrade to Composer 2+. Read more about our Composer 1.x deprecation policy.
This package is abandoned and no longer maintained. No replacement package was suggested.

Services used together with dispatcher.plugin.gitdoc to generate documentation with comodojo/dispatcher.framework

dev-master 2014-12-18 22:54 UTC

This package is auto-updated.

Last update: 2019-02-20 19:51:43 UTC


README

Gitdoc is a comodojo/dispatcher framework service+plugin bundle used to publish the comodojo::docs website.

This plugin is designed to manage different projects' documentation, mantained as markdown files on multiple GitHub repositories.

Build and presentation processes are triggered via GitHub push/tag events; on each (supported) event message, whole docs archive is downloaded from GitHub and parsed to compose static html.

Installation

  1. Install comodojo/dispatcher via composer.

  2. Require comodojo/dispatcher.servicebundle.gitdoc package:

    commposer require comodojo/dispatcher.servicebundle.gitdoc dev-master

  3. Ensure that downloads and docs folders inside dispatcher project are readable/writeable by apache user and add following two lines to dispatcher-config.php:

     define('DISPATCHER_DOWNLOAD_FOLDER', DISPATCHER_REAL_PATH."downloads/");
     define('DISPATCHER_DOC_FOLDER', DISPATCHER_REAL_PATH."docs/");
    
  4. Create gitdoc.json file under config directory; file content should follow this schema:

     {
         "sitename": "Foo docs",
         "description": "Foo Documentation",
         "showHeader": true,
         "showFooter": true,
         "links": {
             "External link": "http://www.example.org"
         },
         "projects": [
             {
                 "name": "bar",
                 "description": "the bar project",
                 "docId": "bar",
                 "hash": "myReallySecureGitHubWebhookHash"
             }
         ]
     }
    
    • showHeader and showFooter are boolean values: if true, header and footer information sections will be displayed
    • each link in links object will add an external href to the top/right menu item
    • each project in project object will declare a new documentation section:
      • name: docsite name
      • description
      • docId (see next section to understand how to use it)
      • hash (optional): secret hook hash
  5. Setup a WebHook on GitHub repository:

    • Payload URL: http://your.documentation.site/receiver/[docId - as in previous section]/
    • Content type: application/x-www-form-urlencoded
    • Secret: hash parameter as in previous section
    • Events: select Create, Delete, Push

Your docsite is now ready to receive updates.

Repository summary

Repository should contain markdown files, one for each chapter, plus one summary.json file like this:

{
    "title": "Foo docs",
    "subtitle": "My fantastic project",
    "chapters": {
        "First chapter": "first.md",
        "Second chapter": "second.md",
        "Foo chapter": "foo.md",
        "Conclusions": "foo.conclusions.md"
    }
}

In chapters object, keys will become chapters name added directly in html.

h1 (#) and h2 (##) headings will be linked to left-sidebar srollspy.

Usage

Just navigate to http://your.documentation.site/docId/ to show your documentation.

Dispatcher will inject routes automatically, one for each project that received at least 1 update.

Because of this behaviour, it is strongly suggested to not add other rules/services into dispatcher instance used to publish docs.