How should I organize a multi-version site?

[jskeet]

My Noda Time site hosts the API reference documentation for multiple versions (all past releases, and the current "unstable" code). Each version also has its own user guide, which needs to refer to the API reference.

Obviously these contain the same type and member names by and large, so even though I can easily generate the metadata (yml files) from the source of previous releases easily enough, I can't use docfx build due to the collisions.

My current plan is to have a separate docfx.json file per release, build the sites as if they were entirely separate, and then stitch them together... but if there's any better approach, I'd love to hear it.

(I considered post-processing the YML files to add the version number to disambiguate, but that would be awkward in various ways, and lead to ugly URLs.)

[bradygaster-zz]

@jskeet I can help you with this. I agree with your opinion of post-processing of YML files. I'll check with our engineering team via @johnneycao to see if there's a "quick-and-easy" way to do this or if they'd have specific guidance on the solution. We'll update you here.

[jskeet]

@bradygaster: Can that work with nice URLs? I'm aiming for URLs such as http://nodatime.org/1.0.x/api/NodaTime.LocalDate.html and http://nodatime.org/1.1.x/api/NodaTime.LocalDate.html - I wouldn't want the "1.0.x" in there twice.

[bradygaster-zz]

Unsure at this time. Would you be comfortable flipping the api and version segment of your URL? cc @johnneycao

[jskeet]

@bradygaster: I'd prefer not to, but I could probably live with it if the upsides were significant. (I think the "current plan" described in the first comment would work, with the downside being that no part of docfx would know about the whole site, so it couldn't generate a title bar or whatever.)

[bradygaster-zz]

I chatted with @johnneycao about this and he's talking it over with the devs and plans on getting some guidance to you shortly. The goal here is obviously to have one DocFX JSON file to drive them all, right? The "workaround" would be if you had to create N sites and wire everything up manually.

[jskeet]

The ideal would be to have a single docfx.json file, yes. But I'd rather sacrifice build cleanliness than end-user URL sanity.

[chenkennt]

@jskeet seems for your solution the only problem is DocFX doesn't support multiple versions of yaml files as there is uid collisions. How about DocFX supports accept multiple sets of inputs (yaml and md) and build them as isolated "doc set"? This should solve your problem about having a single docfx.json and build all content together and have nice URLs as you can specify different output base path for different input sets. I'm wondering are your "doc sets" completely isolated? Will there be any page that needs to cross-reference to page in another version?

[chenkennt]

@jskeet post-processing YAML files could be another way to achieve this. Since the main problem here is the collision in UIDs, if DocFX is able to generate different versions yaml with different UIDs, you should be able to build them together. URLs shouldn't be affected, but that will affect the format of UIDs which is supposed to be stable so that can be easily cross-referenced.

@johnneycao

[jskeet]

@chenkennt: Yes, it might make the cross-referencing itself more painful, too.

If docfx supported the idea of a doc set, that would be great - but I don't want to impose lots of extra complexity on either the implementation or users who don't have this requirement :)

I don't have references between different versions, but I would have one "top level" doc set which referred to each of the versions (but wasn't itself specific to a version). That could be hard-coded in the template if necessary. (That's my current plan.)

[chenkennt]

@jskeet if doc set works for you, we can add this support in our next milestone.

[jskeet]

@chenkennt: It'll be hard to tell how well it works in practice until I've tried it, but it sounds like it would be a good thing. Let me know if I can be of any help in terms of design or trying a proof-of-concept.