Make documentation for old versions available

chaijs / chaijs.github.io

The chaijs.com website source code. Contributions welcome.

http://chaijs.github.io

49 stars 71 forks source link

Make documentation for old versions available #178

Open hiredgunhouse opened 5 years ago

hiredgunhouse commented 5 years ago

For a library like Chai I think it is very important to have the docs for old versions available online. Having docs for the latest version only is problematic for people who are on projects using some older version because new APIs are not available to us and we can only learn that by trial and error.

keithamus commented 5 years ago

Hey @hiredgunhouse thanks for the issue.

I agree with this. It would indeed be great. Right now the docs are generated from the source code, you can see in the https://github.com/chaijs/chaijs.github.io/ repo there is a Makefile which has an api-docs task which does this: https://github.com/chaijs/chaijs.github.io/blob/master/Makefile#L16.

It would take some work but I think it is do-able to have the Makefile generate multiple datasets from different versions, then re-architect the site docs to point to a specific version.

If you have the time to make a PR I'd love to see what you come up with, and I'm also happy to help where I can.

yuki-93 commented 5 years ago

Maybe it would be nice to show for each api assertion, from which minimum version it is available in chai. Just my two cents, if this might be easier to implement.

keithamus commented 5 years ago

Supporting a "version introduced at" piece of meta is also possible - but we could add this as an annotation to the doc blocks in the code comments. It'd be less difficult to implement overall but would probably be more work going through every method in the codebase and figuring out when it was available.

There's one subtle problem with just documenting when a method was introduced: often methods are removed, or change - this is more complex than just availability. For example some assertions only used to accept numbers but now accept dates as well - how can this be articulated?

hiredgunhouse commented 5 years ago

Hey @keithamus, sounds good, I'll give this a shot and try to make a PR. I'll start with generating docs for multiple versions and then think about the tracking of when specific API has been introduced, which, as you pointed out, is a bit more complex subject. BTW. Please have some patience as for the next 2 weeks I'll be busy with some other work.

keithamus commented 5 years ago

@hiredgunhouse thanks for picking this up! Let me know if you need any assistance with this. I'll try my best to offer advice where I can 😄

hiredgunhouse commented 5 years ago

@keithamus a quick update: I'm slowly working through this, please be patient.

harrytruong commented 5 years ago

Thanks @hiredgunhouse for looking into this!

Workaround (for future people trying to find older API docs):

The API docs are being generated from comments in the source code. It's not pretty, but if you search through this file, you might find what you were looking for:

https://github.com/chaijs/chai/blob/3.5.0/lib/chai/core/assertions.js

Select your release version through the github "tags"