Proposal for versioned documentation #13
Conversation
Signed-off-by: Richard Edgar <[email protected]>
Signed-off-by: Richard Edgar <[email protected]>
Signed-off-by: Richard Edgar <[email protected]>
versioned-docs.md
Outdated
|
|
||
| 1. Update links on the custom-designed landing page to go to this new `main` directory. | ||
|
|
||
| 1. Create a `v0.4.6` directory in `fairlearn.github.io`, and do a documentation build corresponding to the `v0.4.6` tag in this directory. This may well have to be done manually. |
There was a problem hiding this comment.
Everything is built from the fairlearn repo, so we wouldn't manually create these directories, but rather instruct our pipeline to put the results of the builds there. We should keep treating the website repo as something we can delete at any point and it gets fully recreated with the next push.
There was a problem hiding this comment.
Problem then is getting the v0.4.6 documentation (although your point about automation is well taken). Right now, a huge pain point is that people install from PyPI, and then try reading the docs here.
If we're willing to leave that problem to one side (in the hopes of v0.4.7 coming out soon after whatever work this requires), then full automation is certainly an option.
There was a problem hiding this comment.
I'm not sure I understand. This problem is unrelated to any particular version since we just need to start at some point, right?
There was a problem hiding this comment.
It's just that v0.4.6 is a particular problem right now. Having said that, the packages you listed below do appear to support pattern matching on tags and the like, so that might be able to do the necessary.
| @@ -0,0 +1,23 @@ | |||
| # Versioned Documentation | |||
There was a problem hiding this comment.
Please link this somewhere as well fairlearn/fairlearn#482
There was a problem hiding this comment.
This mention links it :-)
| 1. Create a `v0.4.6` directory in `fairlearn.github.io`, and do a documentation build corresponding to the `v0.4.6` tag in this directory. This may well have to be done manually. | ||
|
|
||
| The last stage will at least give us a set of documentation corresponding to the version of Fairlearn on PyPI, which we can share with people who run into difficulties. | ||
|
|
There was a problem hiding this comment.
Any idea about the tools you want to use for this? @cedarfall looked into some of them recently and found:
There was a problem hiding this comment.
Will do some more reading. When I was writing this, I was primarily thinking about the v0.4.6 issue (not to mention the even older versions for which all the sphinx docs will vanish).
There was a problem hiding this comment.
I don't think we need to care. Scikit learn starts somewhere around 0.17 or so and that's fine.
There was a problem hiding this comment.
I didn't mean to go back to the beginning, but I would like to be able to generate docs for v0.4.6.
I've been reading the docs for both sphinxcontrib-versioning and sphinx-multiversion. Both look like they can go back to older versions just fine.
Comparing:
https://github.com/sphinx-contrib/sphinxcontrib-versioning
and
https://github.com/Holzhaus/sphinx-multiversion
I'm a little concerned that the former hasn't had any activity since last December, and it was mostly 'done' back in 2016. I'll start by seeing that sphinx-multiversion can do.
There was a problem hiding this comment.
Been trying to persuade sphinx-multiversion to work... have wound up filing an issue on it :-/
Signed-off-by: Richard Edgar <[email protected]>
Signed-off-by: Richard Edgar <[email protected]>
Signed-off-by: Richard Edgar <[email protected]>
Signed-off-by: Richard Edgar <[email protected]>
|
Is our expectation that all of our examples will be continuously updated to work with the most recent version? I wonder whether it wouldn't be better to allow installation instructions at the beginning of examples to use, e.g., Especially, if we allow examples to rely on arbitrary visualization packages, it might be better to have a frozen version of the installation instructions for each example notebook? |
Simple proposal for getting started on versioned documentation