[DOC] Refactor examples directory and link to docs/source/examples #6210
Conversation
duydl
requested review from
achieveordie,
benHeid,
fkiraly and
yarnabrina
as code owners
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
duydl
changed the title
|
@fkiraly hi. sorry I didn't pay attention but seems like this PR is missed somehow. |
fkiraly
changed the title
There was a problem hiding this comment.
Apologies, I indeed missed this. I mistakenly filed it under, another core dev has replied (not sure why).
Thanks a lot for looking into this!
My main comment revolves around the user journey - is important content adequately presented with priority?
There are "major", "secondary", and "minor" tutorials in my mental model.
- major - entry guide for a task or module, e.g., forecasting intro. Basis guide to the framework.
- secondary - follow-on from the entry guide, focus on one specific topic, e.g., probabilistic, hierarchical, etc. Require knowledge of basis guide, and are a manual to advanced features.
- minor - cover specific estimators, use cases, research studies, etc - example: catch22. Does not cover any (or only minimal) framework content. These are interesting but not of primary importance to learn how to use
sktime.
Imo users should be pointed prominently to the major guides, and from there, or after that, to the secondary ones. The "minor" ones should be showcased somehow, but not be presented with equal prominence, as that could confuse users and is typically not what they are looking for primarily.
So far, how we managed it is the numbering, which lets the "major" notebooks appear at the top.
If we move things into folders (e.g., 03_transformers which is important), this structured user journey gets a bit muddled.
So the main question would be, how do we keep your great changes, but also ensure we have a structured user journey? I don't have a "prescriptive" answer, but I think we should spend a round of thinking on this.
|
I assume this is in terms of the root examples / binder because the current arrangement mirrors that of the docs till now. Then the solution would be to move all the important (numbered) notebooks out of subdir into examples/ and just include them manually in the relevant section on examples page. Then those notebooks would also be auto added to the user guide page which is probably another desirable outcome. |
|
For more detail user journey like you envision, this would involve editing the notebooks themselves. It would probably resemble the user-guide of scikit-learn, some would have links to relevant examples in the middle, as well as references to white paper etc. |
Yes, I think that's a good quick way to get close to the optimal state.
That's more work, so perhaps not for this PR? |
|
@fkiraly I moved the numbered nb into examples and added those manually to examples.rst . It is only based on whether one is numbered as there some cases may need clarified in the future:
Two versions. What are the plans for these?
They are all very short with nearly identical content. Consider combining?
Yes. And other nb specific adjustments also IMO. Would be a good task for GSoD i.e going through the current notebooks, optimizing, linking etc. |
There was a problem hiding this comment.
Thanks a lot for going through this!
I think the hierarchy you propose makes sense.
Two versions. What are the plans for these?
These relate to two benchmarking frameworks currently in sktime. We intended to unify these, but the project did not get carried out yet. For now, I think it makes sense to present both.
They are all very short with nearly identical content. Consider combining?
These are weird notebooks. I don't think there is any added content, compared to the main notebook, we just fit some estimators here on random data? I would advocate to remove these entirely. Didn't realize we had these.
Would be a good task for GSoD i.e going through the current notebooks, optimizing, linking et
Yes, absolutely! I included it as a point 1 next to the 3 detail points you elaborated on.
|
Sorry, I forgot to revert the change of image links in one notebook after returning its location. |
#### Reference Issues/PRs #6108 #6106 #### What does this implement/fix? Explain your changes. This PR improves the local documentation build process to be more consistent with the online documentation and reduce build times for better observability. 1. Move Makefile into the source folder, as some functions of conf.py should be run inside source folder like in Readthedoc as stated in .readthedocs.yml. 2. Removed `sphinx-apidoc` and related code as it was not configured in conf.py and so was not used by the build process on Readthedocs. This eliminates orphan pages in the local build documentation that are not present in the online documentation. For example:  which does not appear in online doc: https://www.sktime.net/en/stable/api_reference/auto_generated/sktime.alignment.base.html 3. No longer remove build folder. Instead, add a clean target for situations where a clean build is necessary. This change allows sphinx-build to detect changes in both the documentation and the codebase and do its increment build from cache. 4. Commented out `symlink_examples.sh`. Currently each example in docs is manually linked to sktime/examples. We must refractor the sktime/examples folder to the same structure assumed by docs before we could link it. This change is made in #6210. 5. Added an autobuild target using sphinx-autobuild. 6. Modify docs page on building documentation locally to reflect the changes The new Makefile significantly reduces build times for incremental changes, about 10 times faster than before. #### Does your contribution introduce a new dependency? If yes, which one? No. But users could independently install `sphinx-autobuild` if needed. #### What should a reviewer concentrate their feedback on? This PR won't have any effect on the online documentation. Please confirm on the efficient and consistent of local documentation build with online docs if you have time. #### Any other comments? > 4. Commented out `symlink_examples.sh`. The `symlink_examples.sh` file served no purpose, even before this PR, as the symlinks to examples are tracked. I keep it in the repo in case we need to dynamically create symlink to docs in the future.
Reference Issues/PRs
Fixes #6148.
What does this implement/fix? Explain your changes.
I rearranged the examples dir to be similar to the docs/source/examples, replaced docs/source/examples containing individual sym links inside with just one directory sym link to examples, and adjusted the path of some image links.
For comparison:
https://www.sktime.net/en/stable/examples.html
https://duydlsktime.readthedocs.io/en/patch-docs-examples-0/examples.html in case PR docs not yet rendered