Generating API documents in Git Workflow

Question

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.

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.

Answer 1

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.