Best Practices for multi-repo docs

[bexelbie]

asciibinder seems to be a sitebuilder/docbuilder combination. If your docs are spread out across multiple repos, we should provide guidance on how to build the documentation site.

I don't see a clear path forward because the generated files contain the breadcrumbs and navigation. Therefore if I generate a bunch of packages and copy them to the same place, I don't get full navigation.

One idea would be to add a git branch change hook to asciibinder. This would allow a custom script to get called everytime asciibinder changed branches. My custom script could clone a bunch of repositories into the current directory and checkout the proper branches. It could then generate a full _topic_map.yml file. After this control could return to asciibinder which wouldn't know it was operating on material not actually in git.

Is there an easier way I am not thinking of?

[nhr]

My main idea on this subject has been to extend the _topic_map.yml syntax to enable the inclusion of topics from remote sources. Right now topic entries are:

Topics:
  - Name: Foo
    File: foo

But we could make the File property optional and start supporting a URL property as well. This would enable us to pull in any remote file at build time even if it is not part of the local repo, We could then clean them out again (or move them aside) which changing branches to do the same thing for the next branch-wise builds.

Does that seem like a sensible approach?

[bexelbie]

This is very reasonable. I wasn't expecting the project to want to support this directly :)

However, it would be nicer if I could somehow tell asciibinder, possibly via _distro_map.yml that an entire doc set/version resides in a specific repo and branch. Then it could use that _topic_map.yml.

The challenge here, I think, is that the navigation won't be able to be resolved until all of those topic maps are loaded.

Perhaps we could swap the navigation to reference a file created at the end and use some javascript (or other magic) to do the navigation and breadcrumbs.

This could also make integrating translations easier.

[bexelbie]

So I have been continuing to think about this. I am adding more to the situation because of my use case. I need to handle a documentation set that is built from documentation in multiple repositories and that has been translated in zanata to multiple languages.

I have some preprocessing that builds out an asciibinder capabile repository. Basically, I do the following for the multi-repository use case:

1. Visit each branch of the repository from which asciibinder will be run
2. add each document repository as a git-subtree in the _git directory and then symlink the documentation into place in the root directory
3. build out the _topic_map.yml to include all maps.
4. Commit everything
5. When done with all branches, run asciibinder

To add languages, I am looking at retooling this to building out a language subtree for each set and dynamically generating language specific _topic_map.yml entries. There are still a few gotchas here. I am thinking, it would be nice if ascii_binder could understand that there is a set of languages to build and the idea that it should template them out using a $lang variable substituion in both paths and as an attribute in AsciiDoc. This could then call something to do the templating that would marry in the zanata output.

Again, I am not sure how much of this is me overthinking the problem or pushing asciibinder past where it should go. The idea of scaffolding scripts is kind of ugly, but does open up a world of possibilities. This would continue to require hooks at branch change or other processing points. It may also be harder to do on Windows, if that is a target platform (OS X should behave like Linux here).