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 · 20 comments

Comments

Projects
None yet
7 participants
@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

This comment has been minimized.

Show comment
Hide comment
@bradygaster-zz

bradygaster-zz 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.

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

This comment has been minimized.

Show comment
Hide comment
@jskeet

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

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

This comment has been minimized.

Show comment
Hide comment
@bradygaster-zz

bradygaster-zz Jun 20, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@jskeet

jskeet 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.)

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

This comment has been minimized.

Show comment
Hide comment
@bradygaster-zz

bradygaster-zz 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.

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

This comment has been minimized.

Show comment
Hide comment
@jskeet

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

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Jun 21, 2016

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Jun 21, 2016

Contributor

@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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@jskeet

jskeet 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.)

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Jun 23, 2016

Contributor

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

Contributor

chenkennt commented Jun 23, 2016

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

@jskeet

This comment has been minimized.

Show comment
Hide comment
@jskeet

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

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

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jul 12, 2016

Collaborator

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

Collaborator

superyyrrzz commented Jul 12, 2016

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

@bradygaster-zz

This comment has been minimized.

Show comment
Hide comment
@bradygaster-zz

bradygaster-zz Jul 12, 2016

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

bradygaster-zz commented Jul 12, 2016

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

@jskeet

This comment has been minimized.

Show comment
Hide comment
@jskeet

jskeet 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...)

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

This comment has been minimized.

Show comment
Hide comment
@bradygaster-zz

bradygaster-zz 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.

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

This comment has been minimized.

Show comment
Hide comment
@jskeet

jskeet Jul 21, 2016

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

jskeet commented Jul 21, 2016

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

@jskeet

This comment has been minimized.

Show comment
Hide comment
@jskeet

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

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

This comment has been minimized.

Show comment
Hide comment
@chenkennt

chenkennt Jul 22, 2016

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@pvandervelde

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

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

This comment has been minimized.

Show comment
Hide comment
@superyyrrzz

superyyrrzz Jul 22, 2016

Collaborator

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

Collaborator

superyyrrzz commented Jul 22, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment