Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How should I organize a multi-version site? #396

Closed
jskeet opened this issue Jun 19, 2016 · 28 comments
Closed

How should I organize a multi-version site? #396

jskeet opened this issue Jun 19, 2016 · 28 comments
Assignees
Milestone

Comments

@jskeet
Copy link

@jskeet jskeet commented Jun 19, 2016

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
Copy link

@bradygaster-zz bradygaster-zz commented Jun 20, 2016

@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
Copy link
Author

@jskeet jskeet commented Jun 20, 2016

@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
Copy link

@bradygaster-zz bradygaster-zz commented Jun 20, 2016

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

@jskeet
Copy link
Author

@jskeet jskeet commented Jun 20, 2016

@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
Copy link

@bradygaster-zz bradygaster-zz commented Jun 20, 2016

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
Copy link
Author

@jskeet jskeet commented Jun 20, 2016

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
Copy link
Contributor

@chenkennt chenkennt commented Jun 21, 2016

@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
Copy link
Contributor

@chenkennt chenkennt commented Jun 21, 2016

@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
Copy link
Author

@jskeet jskeet commented Jun 21, 2016

@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
Copy link
Contributor

@chenkennt chenkennt commented Jun 23, 2016

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

@jskeet
Copy link
Author

@jskeet jskeet commented Jun 23, 2016

@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.

@chenkennt chenkennt added this to the v2.2 milestone Jun 30, 2016
superyyrrzz added a commit to superyyrrzz/docfx that referenced this issue Jul 4, 2016
superyyrrzz added a commit to superyyrrzz/docfx that referenced this issue Jul 4, 2016
@superyyrrzz
Copy link
Contributor

@superyyrrzz superyyrrzz commented Jul 12, 2016

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

@bradygaster-zz
Copy link

@bradygaster-zz bradygaster-zz commented Jul 12, 2016

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

@jskeet
Copy link
Author

@jskeet jskeet commented Jul 12, 2016

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
Copy link

@bradygaster-zz bradygaster-zz commented Jul 12, 2016

@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
Copy link
Author

@jskeet jskeet commented Jul 21, 2016

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

@jskeet
Copy link
Author

@jskeet jskeet commented Jul 21, 2016

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
Copy link
Contributor

@chenkennt chenkennt commented Jul 22, 2016

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
Copy link

@pvandervelde pvandervelde commented Jul 22, 2016

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
Copy link
Contributor

@superyyrrzz superyyrrzz commented Jul 22, 2016

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

@TheReaLee
Copy link

@TheReaLee TheReaLee commented Sep 18, 2019

@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
Copy link
Contributor

@superyyrrzz superyyrrzz commented Sep 18, 2019

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

@thuannguy
Copy link

@thuannguy thuannguy commented Oct 9, 2019

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
Copy link
Contributor

@superyyrrzz superyyrrzz commented Oct 12, 2019

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

@thuannguy
Copy link

@thuannguy thuannguy commented Oct 12, 2019

@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
Copy link
Contributor

@superyyrrzz superyyrrzz commented Oct 12, 2019

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

@thuannguy
Copy link

@thuannguy thuannguy commented Oct 12, 2019

Thank you very much 😄

@gblikas
Copy link

@gblikas gblikas commented Mar 24, 2020

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
10 participants
You can’t perform that action at this time.