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.

[superyyrrzz]

It's implemented in dev branch, and will ship in DocFX v2.2.

[bradygaster-zz]

pinging @jskeet to make sure he sees this update. Thanks for the update on the issue @superyyrrzz!

[jskeet]

Yup, I saw - thanks very much, I'm really looking forward to it. (I'm dreaming of being able to ditch SHFB and Jekyll in Noda Time...)

[bradygaster-zz]

@jskeet nice to hear. will look forward to more feedback. once you get the release let us know if things are ok by closing the issue. if you find any other opportunities let us know.

[jskeet]

I see it's available now :) Will try it out...

[jskeet]

Okay, I've made a lot of progress on this. I can't get links to work without a warning from the top-level TOC, but the link does point to the right place in the end result. That said, I haven't managed to get the "versioned" parts to keep a TOC along the top... either a version-specific one or the non-specific one. I can see there being lots of different expectations from different users here, so it's definitely a difficult problem.

Presumably this scenario is still viewed as "in progress" in general? Once there's a complete story, it would be great to have a full example. I'd be very happy to work with someone on the team (video call maybe?) to help develop that if it would be useful. Obviously the set-up I've got in Noda Time isn't the only one that might occur, but it could be a handy starting point as a concrete example.

[chenkennt]

Currently versions are isolated so you cannot create links between versions using relative path (i.e. you cannot link to a markdown file in another version using [text](path.md) and expect it to be resolved as <a href="path.html">. But you can create links using output path (like [text](version/path.html)). DocFX will give warning as .html doesn't exist in source but it will eventually become a clickable link if you have an output file named version/path.html.

We do have plan to support link between versions but we're still thinking what is a good user experience. This is bit complicated if you want to cross reference API topics in difference versions. For example, what if you want to reference a .NET 2.0 System.String in 4.0 documentation? They have the same qualified name so we need to come up with a new syntax to support it. So if you have any input we're very happy to discuss with you about what the best user experience would be.

[pvandervelde]

This all sounds very useful. Is there any documentation on how this works or even just some examples? I'd like to try this out myself.

[superyyrrzz]

@pvandervelde You can find a sample docfx.json here. We still haven't detailed documentaion, hope this can help.

[TheReaLee]

@pvandervelde You can find a sample docfx.json here. We still haven't detailed documentaion, hope this can help.

By any chance, have you released detailed documentation on this? TIA.

[superyyrrzz]

@TheReaLee Not yet. DocFX supports this with limited out of box features. Nodatime could be a nice sample, but it has much customization.

[thuannguy]

What is the magic that docs.microsoft.com is using to do versioning? e.g. https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-3.0&tabs=visual-studio

Is that something that can work out of the box with DocFX or?

[superyyrrzz]

Currently, it relies heavily on closed source components. The will be available in v3.

[thuannguy]

@superyyrrzz oh, that's great. Do you have a timeframe for approximately when v3 will be release? E.g. later this year or what quarter next year?

[superyyrrzz]

Not soon, but you can track it here: https://github.com/dotnet/docfx/blob/v3/docs/roadmap.md

[thuannguy]

Thank you very much 😄

[gblikas]

@superyyrrzz Is there a way to set a "latest" version, automatically inferred by the docfx.json file? So, that way there is a "go to latest" reference.