Use git branches to determine versions

[tyler-sommer]

It would be useful if the documentation repository's branching model could match the project repository's and generate matching documentation.

I think it would be worthwhile to implement versioning based off of the documentation repository, as an alternative to folders.

[tyler-sommer]

It looks like to implement this, we may need to pre-generate the documentation since we would need to checkout each version to get the contents.

What are your thoughts on creating a way to pre-generate all the documentation, thus making a sort of static site? We could leave the dynamic router in front of the static HTML to keep URLs the same between dynamic/static docs. We could expose a configuration option and an artisan command that would generate all the docs.

[kaidesu]

It would be useful if the documentation repository's branching model could match the project repository's and generate matching documentation.

I guess I'm a little fuzzy on the functionality/purpose behind this. What would the use case be (ie, how would it be used)?

It sounds cool, but it also sounds a bit overly complicated to set up rather than simply creating a couple directories and writing documentation.

[tyler-sommer]

Yeah, I agree that it would add quite a bit of complication. Here's my use case:

• We have a project repository project and it has the following tags and branches: 1.0.0, 1.1.0, master
• We have another repository called project-docs and it has the same tags and branches: 1.0.0, 1.1.0, master

The documentation repository follows the project's branching/tagging model. If you want docs for project version 1.0.0, you checkout project-docs at the 1.0.0 tag. The reasoning here is often times, the documentation between 1.0.0 and 1.1.0 is only very slightly different (so why actually duplicate the files, DRY type thing). Additionally, working this way allows you to leverage git very easily: you can diff documentation between versions with git diff 1.0.0 1.1.0, you can merge documentation changes between branches with git merge, etc.

So, set up for this within Codex might work something like:

1. Install Codex
2. "Install" the documentation repository into Codex: Open up the storage directory, git init and git remote add origin git@mycompany.com:project-docs.git and git pull --mirror
3. Edit codex.php configuration file to let Codex know that it should look at the git repository's branches and tags (rather than the folder structure) to determine versions.
4. Run an artisan command like ./artisan gen-docs which would go through, check out all the branches and tags, and generate static HTML files that would then be served through the CodexController.

Steps 3 and 4 don't yet exist. Step 4 could also be leveraged for regular "folder-based" documentation, as well, to improve performance (could be a straw man argument-- I dont know if there is a point where Parsedown will be noticeably slow in rendering a document)

Really there are two distinct features: pre-compilation of docs, and using git for versioning. Do you think either of these features belong in Codex?

[kaidesu]

I see.

I don't think we'd need a gen-docs command specifically. A simple method to serving pre-generated static pages would be to just implement caching on the page - which would cache the generated HTML page for X amount of minutes. This would be a simple update as well (which I believe the Laravel website does for their documentation too).

Pulling down a git repository specifically for the documentation files would be cool though. I can't think of a way to somehow automate this via PHP/Laravel though.

[tyler-sommer]

Good call about the caching, that's a much better solution.

As far as automating Git stuff, Composer implements some stuff to mess with Git: https://github.com/composer/composer/blob/master/src/Composer/Util/Git.php. We could do similar.

Let me see if I can get a minimal version working, then we can use it as a starting point for further discussion regarding whether it actually fits Codex's scope and if we can simplify and automate things.

[kaidesu]

👍

[kaidesu]

I've added cache support with commit 289caca.

[kaidesu]

@tyler-sommer I've added the ability to choose which driver method you'd like to use (opening the door to easily switch between flat and git through the Codex config file) - I've also written documentation on extending and creating you're own driver. Should provide a solid base to work in Git integration.

Commit: fca399e

[tyler-sommer]

Thanks, @kaidesu, I appreciate it. I'll take a look and incorporate the changes into my code.

[kaidesu]

Works pretty great so far~ I got the Codex Docs repository initialized with the current codex documentation (branched 1.0.0 and master). Once things are further tested and the code is cleaned up, I think we'll be good.

The only tweak I can see right now is adding the ability to choose if you want the master branch to be the default version or default to the latest stable x.x.x branch.

[tyler-sommer]

Awesome, I'm glad to hear it's working! I've got it up and running at niceframework.com and I'm working on getting https://github.com/terramar-labs/packages-docs up somewhere as well. Being able to specify a default version would be killer!

[kaidesu]

I've cleaned up the code quite a bit, fixed a few bugs, and implemented an AbstractCodexRepository class to take care of some of the methods that were duplicates (and most likely will always be for any storage driver implementation).

With that, I'll be releasing v1.1.0 very soon if there are no major issues with the latest master branch.

I'm going to go ahead and close this issue and call it complete though. Thank you for the contribution and time spent working on this! I had a blast~