Docs/mkdoc

[PGijsbers]

Work converting the Python docs to mkdocs. Left to do before it's "functional":

• [ ] Make sure notebooks run
• [ ] Add the test server warning back, preferably in a reusable way as was before.

Otherwise, most of the files have been converted.

That said, the documentation really needs a rewrite. I refrained from changing any content as much as I could, with rare exceptions. But the main problems, to me, are:

• Information is all over the place. A few cohesive examples with a proper ToC would be better (I think).
• The formatting is bad.
• There is a mix of styles. Some examples even talk about "exercises" (e.g., here).
• Some of the content is outdated.

How should we move forward with this PR? I don't mind rewriting (some of) this documentation, but I think it would be better to merge this at one point so it's easier to collaborate. WDYT? @eddiebergman @LennartPurucker

[LennartPurucker]

IMO: merge first and focus on user stories/use cases afterward to refactor the documentation. That is, likely move all the old documentation to an "extended example" list and only keep a set of user stories / use cases in the new main documentation.

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 53.71%. Comparing base (c66d22a) to head (2a16c03). Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1379   +/-   ##
========================================
  Coverage    53.71%   53.71%           
========================================
  Files           38       38           
  Lines         5229     5229           
========================================
  Hits          2809     2809           
  Misses        2420     2420           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[PGijsbers]

Hey @SubhadityaMukherjee, thanks a lot for picking this up! To clear up some confusion: you approved the PR but in the same comment you say you're still going to test whether or not notebooks/scripts run. Approving the PR should be an indication that it can safely be merged into the develop branch (even if some restrictions may apply, e.g., the documentation is still out of date). Assuming no new need-to-do items were found, then at least the two from the first comment need to be fulfilled (the checkbox items). It's not clear to me now what their status is from this thread. Did you already address those?

[SubhadityaMukherjee]

In response to adding back the server warnings, looks like mkdocs-jupyter does not yet support admonitions. I added it in manually for now since it was only used in 3 places but was unable to find any other way of doing it. (aka it works, but is not reusable without copy pasting a block of text)

[SubhadityaMukherjee]

Seems I forgot to update this. These examples dont work. Im not entirely sure how to fix them. All the other examples seem to run. I modified some slightly to make some of them work. They are from examples/

20_basic/ simple_flows_and_runs_tutorial : the flow seems to be wrong. expected flow parameters: [] model parameters: ['bootstrap', 'ccp_alpha', 'class_weight', 'criterion', 'max_depth', 'max_features', 'max_leaf_nodes', 'max_samples', 'min_impurity_decrease', 'min_samples_leaf', 'min_samples_split', 'min_weight_fraction_leaf', 'monotonic_cst', 'n_estimators', 'n_jobs', 'oob_score', 'random_state', 'verbose', 'warm_start’]

30_extended/ run_setup_tutorial : IndexError: positional indexers are out-of-bounds

flows_and_runs_tutorial : No reg-eye-state, or dataset 68 seems to be something else.

study_tutorial: the flow seems to be wrong. ValueError: Parameters of the model do not match the parameters expected by the flow: expected flow parameters: [] model parameters: ['bootstrap', 'ccp_alpha', 'class_weight', 'criterion', 'max_depth', 'max_features', 'max_leaf_nodes', 'max_samples', 'min_impurity_decrease', 'min_samples_leaf', 'min_samples_split', 'min_weight_fraction_leaf', 'monotonic_cst', 'n_estimators', 'n_jobs', 'oob_score', 'random_state', 'verbose', 'warm_start’]

40_paper/ 2018_kdd_rijn_example.py: This example is deprecated, remove the if False in this code to use it manually.

[PGijsbers]

Thanks! I can have another look once AIoD calms down a little (i.e., after May 22nd).

[SubhadityaMukherjee]

Removed linkcheck for now since the one I picked apparently is not maintained. Also an option for versioning using "mike" which requires some extra work. - https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/

[SubhadityaMukherjee]

Ah @PGijsbers I think we will also need to point the gh-pages option in settings to a different page. I dont have access to it so I cant check if its the same as sphinx. It should be Pages -> Deploy from branch : gh-pages -> root

[PGijsbers]

Ah @PGijsbers I think we will also need to point the gh-pages option in settings to a different page. I dont have access to it so I cant check if its the same as sphinx. It should be Pages -> Deploy from branch : gh-pages -> root

That's already set. Sorry for the slow reply. Next time just ask me directly if I don't respond :)

[SubhadityaMukherjee]

all the tests pass in reality but the added files check fails, maybe mike adds them. Im looking into it