Overhaul documentation homepage #3836
Conversation
|
@mlpack-jenkins test this please |
|
@mlpack-jenkins test this please |
|
@rcurtin is this ready for review ? |
|
Let me fix the documentation build... I thought that would be easy but it has taken a few iterations. I should have marked this as a draft initially, I'll do that now until I get it passing. |
|
@mlpack-jenkins test this please |
1 similar comment
|
@mlpack-jenkins test this please |
shrit
left a comment
shrit
left a comment
There was a problem hiding this comment.
Looks very good, much better than before.
Here are a couple of things that I have noticed:
-
The first output is equal to the second one, I expected different results as written above:
-
Links to outside of CI (e.g., youtube) are not functional. (Probably this is because it is inside the CI, as we have already discuss it)
-
I think we can the quick start guide to the start, instead of the middle
-
I think we can find a better name instead of the C++ API docs.
-
We can also remove the gray color of the bindings because it looks like a separation bar.
-
Would be interesting to recall Matrics and data to "Matrices representation in mlpack".
-
Finally, in the CI page I have noticed that in the docs section we are referring to how to build the docs locally, I think we can keep it for now, but I do not think idealy this should be the place for it, it is better to have a unique page for the docs, as others might be interested contributing.
Overall looks good, we can get it merged when all of these small modifications get resolved. Amazing work
| * the [test program compilation section](doc/user/install.md#compiling-a-test-program) | ||
| of the installation documentation, |
There was a problem hiding this comment.
The sentence is slightly confusing, I can understand because I know what was here, but we maybe we can change it to something like Compiling a test program?
|
@mlpack-jenkins test this please |
1 similar comment
|
@mlpack-jenkins test this please |
They're actually not exactly the same, there is also a backtrace line in the first program output.
Right, this had to do with the content security policy that Jenkins was using (more here). I'm still tuning this, but I have a configuration that works now. (It's actually quite insecure, but I am trying to see how much I can lock it down without breaking the documentation build.)
Agree, fixed in 3e28d76.
Do you have any suggestions on this one? I thought about it for a while but I haven't come up with anything. I do want to distinguish it from the binding documentation (which is not in C++), so I think we need to keep the C++ term in there.
Done in 9cc2ae9.
How about "Data representation in mlpack"? Changed in e4a2bf4.
The I do agree that we should eventually have a page discussing how to write documentation, what needs to be documented, and how to test it (including these scripts); basically a guide for new contributors. But I didn't write that yet; here I just wanted to write down that these scripts exist and are run in CI.
Thanks! It took forever to figure out how to do all the links in the SVGs and everything like that. |
shrit
left a comment
shrit
left a comment
There was a problem hiding this comment.
Looks good to me, and Data representation in mlpack works 💯
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
Sorry this sat for so long, but I got the documentation build to pass (still have not cleaned up that job yet) so let's go ahead and merge. |
2 participants
This PR remakes the homepage of the documentation in a clearer way, following the discussions in #3803.
Here is the built documentation:
(It took a little while to get Jenkins to render that correctly! I am still playing with security policies.)
The basic bits of the overhaul are:
mlpack algorithms and functions are now organized by roughly where they might sit in a data science pipeline (which goes from data loading to preprocessing all the way to deployment). The homepage has a drawn-out SVG (which has a 'narrow' version for mobile devices too) that organizes the documentation in an easily clickable way. The 'landing pages' for each step in the pipeline have where they are in the pipeline at the top of the page.
The sidebar is now a complete page map; every
.mdfile has a corresponding link in the sidebar. The hierarchy of the sidebar matches the pipeline stages above.The documentation now links to the Youtube videos I recorded some time back. :)
The community page was updated to have the mlpack video chat on the first Monday of every month. And I will actually post about it in #mlpack each month...
I added
ci.md, which documents the CI systems we have. There is a lot of hidden knowledge about those, so I tried to write some of it down. I'm sure that will improve over time.I also added
compile.md, a page detailing how you might compile a simple mlpack program, as well as a few other pages about installation, CMake options, and so forth.A little bit of CSS changes to make the sidebar just a bit wider, because it looks really bad when things wrap. (Also: I would like the sidebar to store the "state" of what's expanded and what isn't, but that will take some ~fairly simple Javascript. I'll get to it at some point, but not for this PR.)
Whenever I add the links above (when the build passes), I'll add a link to each new page or page that I changed significantly.
Feedback appreciated!