Generating API documents in Git Workflow

Not sure if this should be here or on Programmers.

Generating API documents

I would like some advice on how I should generate API documentation for an internal project. I am relatively new to Git and we are trying to implement some sound build/deploying practices.

  • Git describe build dependency
  • Using a single gulpfile across projects
  • Jenkins marks good build as failure because of test failed
  • grails add svn revision to app.version
  • Do not delete a Jenkins build if it's marked as “Keep this build forever” - Groovy script to delete Jenkins builds
  • Team City build failing almost as soon as git checkout starts with java.lang.NullPointerException
  • One of the things we discussed was making sure our code base is well documented and generating documentation using something like PhpDocumentor2 or one of the many similar tools.

    We have started to implement a workflow similar to the one detailed here.

    Should I automate when the docs are built?

    For example a pre or post commit hook in git when tagging a release. Or should when I merge develop to a release branch just manually create the docs and commit to the repository?

    Is it standard practice to have docs generated for each release?

    I might have misunderstood the process, should a new doc release correlate with a git release/tag?

    Where do you store the generated docs?

    In the same repository? a different repository? Hosted somewhere like Read The Docs or just internally?
    The current project we are working on is only small, but we would like to roll out the process to other larger projects in the future if successful.


    The project is a Magento extension which we would like to provide API docs, unit testing, and PSR conforming code. I am lacking information on how the whole workflow integrates. PHPunit and PHPDocumentor2 are installed locally via Composer.

    I have heard and looked at Travis Ci, but I’m not sure if Docs fall in to that category.

    This question may seem petty and/or trivial, however, I’ve not much experience in integration and git workflow and I couldn’t find much information around.

  • Are CRLF lines ok in a Rails project deployed on Linux?
  • Best practice to manage source code with multiple skins in Xcode
  • Queue build for non-default branch with git and VS
  • Ansible: how to run task on other host inside one playbook?
  • Using git to deploy to a cluster
  • How to get Jenkins to perform deletes on remote server
  • One Solution collect form web for “Generating API documents in Git Workflow”

    Generated documented generally are:

    • always in sync with the code source (so the question of “should a new doc release correlate with a git release/tag” becomes moot)
    • not stored in a version control referential (like a git repo), but rather (re-)generated at will (in any location you like).

    If you look at a project with a large code source, and an extensive code documentation, you can take as an example the language Go and his repository (a mercurial repo, but you have mirror on GitHub as well)

    • static documentations like the specs, articles, release notes, … are kepts within the repo, as they are not generated, but updated manually, and are tightly linked to the sources.
    • Code documentation is kept separately in a static web site.
    • Documentation for all go project is kept in a static website GoDoc, which will fetch the sources of Go projects, and generate the documentation from them.
    Git Baby is a git and github fan, let's start git clone.