-
Notifications
You must be signed in to change notification settings - Fork 6
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
Proposal for versioned documentation #13
base: master
Are you sure you want to change the base?
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please link this somewhere as well fairlearn/fairlearn#482
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This mention links it :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Once checking in it won't
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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