From 54e1c9b34e64fb2e2b8785b4b8b4ede60888779b Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Mon, 3 Aug 2020 16:44:46 -0400 Subject: [PATCH 1/7] Start working on a proposal for versioned docs Signed-off-by: Richard Edgar --- versioned-docs.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 versioned-docs.md diff --git a/versioned-docs.md b/versioned-docs.md new file mode 100644 index 0000000..18efade --- /dev/null +++ b/versioned-docs.md @@ -0,0 +1 @@ +# Versioned Documentation From 4e61912c278b1b74ee0f1d07a0c5d4e5103222db Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Mon, 3 Aug 2020 16:50:40 -0400 Subject: [PATCH 2/7] Problem description Signed-off-by: Richard Edgar --- versioned-docs.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/versioned-docs.md b/versioned-docs.md index 18efade..193dce0 100644 --- a/versioned-docs.md +++ b/versioned-docs.md @@ -1 +1,6 @@ # Versioned Documentation + +We are starting to run into issues with people trying to use Fairlearn installed from PyPI with the documentation on [our website](https://fairlearn.github.io/). +This is an issue because we have made and are making a number of breaking changes to our API. +The solution to this is to provide versioned documentation, so that users can read the docs associated with the version they have installed. +This is the pattern used by projects such as [SciKit-Learn](https://scikit-learn.org). \ No newline at end of file From cc376a2759d835a37cbec279bcffdd05c76644ca Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Mon, 3 Aug 2020 17:01:05 -0400 Subject: [PATCH 3/7] Fill out the proposal Signed-off-by: Richard Edgar --- versioned-docs.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/versioned-docs.md b/versioned-docs.md index 193dce0..071d91e 100644 --- a/versioned-docs.md +++ b/versioned-docs.md @@ -3,4 +3,21 @@ We are starting to run into issues with people trying to use Fairlearn installed from PyPI with the documentation on [our website](https://fairlearn.github.io/). This is an issue because we have made and are making a number of breaking changes to our API. The solution to this is to provide versioned documentation, so that users can read the docs associated with the version they have installed. -This is the pattern used by projects such as [SciKit-Learn](https://scikit-learn.org). \ No newline at end of file +This is the pattern used by projects such as [SciKit-Learn](https://scikit-learn.org). + +Getting to something as sophisticated as the SciKit-Learn setup will take time. +As a first step, we propose: + +1. Change the CirceCI integration to push to a `main` directory (in preparation for the expected rename of the `master` branch) within the [`fairlearn.github.io`](https://github.com/fairlearn/fairlearn.github.io) repository, rather than pushing to the root of the repository. + +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. + +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. + +For the future: + +1. Automate the creation of the `vx.y.z` subdirectories + +1. Figure out a navigation control for switching between versions, similar to that used by SciKit-Learn \ No newline at end of file From 22c20c1d2ecb50f49d5d4a32365c99e16cd868af Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Fri, 7 Aug 2020 12:12:39 -0400 Subject: [PATCH 4/7] Talking about tooling Signed-off-by: Richard Edgar --- versioned-docs.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/versioned-docs.md b/versioned-docs.md index 071d91e..fdf5147 100644 --- a/versioned-docs.md +++ b/versioned-docs.md @@ -5,19 +5,18 @@ This is an issue because we have made and are making a number of breaking change The solution to this is to provide versioned documentation, so that users can read the docs associated with the version they have installed. This is the pattern used by projects such as [SciKit-Learn](https://scikit-learn.org). -Getting to something as sophisticated as the SciKit-Learn setup will take time. -As a first step, we propose: +The basic pattern is to change the layout of the `fairlearn.github.io` repository so that there is a directory for each version of the documentation. +There is then a root level `index.html` to redirect users to an appropriate default directory (either latest release, or the development branch). +See the [SciKit-Learn documentation repo](https://github.com/scikit-learn/scikit-learn.github.io) for an example. -1. Change the CirceCI integration to push to a `main` directory (in preparation for the expected rename of the `master` branch) within the [`fairlearn.github.io`](https://github.com/fairlearn/fairlearn.github.io) repository, rather than pushing to the root of the repository. +There are tools to help with this, such as: +- [sphinx-multiversion](https://pypi.org/project/sphinx-multiversion/) +- [sphinxcontrib-versioning](https://pypi.org/project/sphinxcontrib-versioning/) -1. Update links on the custom-designed landing page to go to this new `main` directory. +The latter of these last had a PyPI release in 2016. The last repo commit was in 2019, but there was little activity after 2016. +As such, it is probably not a wise choice. -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. - -For the future: - -1. Automate the creation of the `vx.y.z` subdirectories - -1. Figure out a navigation control for switching between versions, similar to that used by SciKit-Learn \ No newline at end of file +The `sphinx-multiversion` tool has more recent updates, and the author has been very helpful with debugging issues the Fairlearn documentation. +Some of these have resulted from Windows, and the author has issued patches for them. +Unfortunately, there is a more fundamental issue: we have substantially changed the `examples/` directory, and this means that the latest `conf.py` does not work with `v0.4.6`. +This is not compatible with the way `sphinx-multiversion` works. \ No newline at end of file From 5be4e047e69d065044ce43cc513b92b82b5f04fb Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Fri, 7 Aug 2020 14:48:10 -0400 Subject: [PATCH 5/7] Put in a concrete proposal Signed-off-by: Richard Edgar --- versioned-docs.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/versioned-docs.md b/versioned-docs.md index fdf5147..a9d34b4 100644 --- a/versioned-docs.md +++ b/versioned-docs.md @@ -19,4 +19,10 @@ As such, it is probably not a wise choice. The `sphinx-multiversion` tool has more recent updates, and the author has been very helpful with debugging issues the Fairlearn documentation. Some of these have resulted from Windows, and the author has issued patches for them. Unfortunately, there is a more fundamental issue: we have substantially changed the `examples/` directory, and this means that the latest `conf.py` does not work with `v0.4.6`. -This is not compatible with the way `sphinx-multiversion` works. \ No newline at end of file +This is not compatible with the way `sphinx-multiversion` works. + +## Proposal + +We should onboard to using `sphinx-multiversion` going forwards. +However, if we want `v0.4.6` documentation, that will have to be a special case. +It should be relative straightforward to add it to the `fairlearn.github.io` repository manually, once `sphinx-multiversion` has taken over main documentation build. \ No newline at end of file From 8ab89f9573d7c9392e3ae3a3099b59c96becf545 Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Fri, 7 Aug 2020 14:51:38 -0400 Subject: [PATCH 6/7] Add caveat Signed-off-by: Richard Edgar --- versioned-docs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/versioned-docs.md b/versioned-docs.md index a9d34b4..41af49c 100644 --- a/versioned-docs.md +++ b/versioned-docs.md @@ -25,4 +25,7 @@ This is not compatible with the way `sphinx-multiversion` works. We should onboard to using `sphinx-multiversion` going forwards. However, if we want `v0.4.6` documentation, that will have to be a special case. -It should be relative straightforward to add it to the `fairlearn.github.io` repository manually, once `sphinx-multiversion` has taken over main documentation build. \ No newline at end of file +It should be relative straightforward to add it to the `fairlearn.github.io` repository manually, once `sphinx-multiversion` has taken over main documentation build. + +Aside from the `v0.4.6` issue, the risk in this approach is that each version will build all the examples. +That could take us over the time limit for the CircleCI free tier. \ No newline at end of file From 9b450f572fa708f6c4ff713b74c4846e58b0560d Mon Sep 17 00:00:00 2001 From: Richard Edgar Date: Mon, 10 Aug 2020 09:18:40 -0400 Subject: [PATCH 7/7] Add more detail about required changes Signed-off-by: Richard Edgar --- versioned-docs.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/versioned-docs.md b/versioned-docs.md index 41af49c..cde3ff8 100644 --- a/versioned-docs.md +++ b/versioned-docs.md @@ -21,11 +21,25 @@ Some of these have resulted from Windows, and the author has issued patches for Unfortunately, there is a more fundamental issue: we have substantially changed the `examples/` directory, and this means that the latest `conf.py` does not work with `v0.4.6`. This is not compatible with the way `sphinx-multiversion` works. -## Proposal +## Tool Selection We should onboard to using `sphinx-multiversion` going forwards. However, if we want `v0.4.6` documentation, that will have to be a special case. It should be relative straightforward to add it to the `fairlearn.github.io` repository manually, once `sphinx-multiversion` has taken over main documentation build. +We will then at least have a URL we can share with those who encounter issues. -Aside from the `v0.4.6` issue, the risk in this approach is that each version will build all the examples. -That could take us over the time limit for the CircleCI free tier. \ No newline at end of file +Since `sphinx-multiversion` builds every version of the documentation each time and we have some examples which take a while to generate, it is possible that we might start to bump against the time limits of our free CircleCI account. +If this happens, we will have to devise workarounds. + +## Required Changes + +Moving to versioned documentation will require a number of changes to the workings of our `docs/` directory. + +Our static, professionally designed landing page should be removed from the Sphinx build. +The assets should be saved in a separate directory, and copied to the appropriate location by a script after the main documentation has been built. + +To access the different versions of the documentation, `sphinx-multiversion` [provides two samples](https://holzhaus.github.io/sphinx-multiversion/master/templates.html) of HTML fragments which can be generated with appropriate links. +Unfortunately, it appears that currently the `pydata-sphinx-theme` we're using does not currently support customised sidebars. +I have [opened an issue on their GitHub repo](https://github.com/pandas-dev/pydata-sphinx-theme/issues/234) about this, and it has been acknowledged. +If no better solution can be found, then I can adjust the generated code from `sphinx-multiversion` to be a full webpage, and have it redirect to the `master` version after a pause of five seconds. +The 'User Guide' links on the static landing page can then point to this version-selection page.