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.

  • How can I ignore build directory in Subclipse?
  • Building Eclipse IDE from scratch - how to specify the target OS?
  • Trigger hudson build when svn commit
  • How to generate .ipa file from command line with watchkit app
  • Gradle - multiple project and git repositories
  • Jenkins Build Flow Plugin sequentially chain multiple jobs in parallel
  • 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.

    Context

    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.

  • How can sbt pull dependency artifacts from git?
  • How to properly use CI scripts with Git hooks to compress source
  • TFS Labels in a Build Continuous Environment with Jenkins
  • Fatal: could not read Username for 'https://github.com': No such device or address
  • Git Deploy PHP App to MULTIPLE EC2 Nodes
  • Using 'git checkout -f' to deploy files from a bare git repo in Gitlab
  • 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.