Set up documentation #59
Conversation
Is this supposed to be |
|
Yes, good catch! |
There was a problem hiding this comment.
Hey @aazuspan, this is a very impressive first cut. Thank you for putting so much effort into it. mkdocs looks really intuitive ... I love the YAML config to build the site. It's much more satisfying to write documentation if it's formatted nicely right from the start!
I've responded to some, but not all, of your comments below. It sounds like I need to take a cut at edits to some of the content, which I'm happy to do and hopefully that will address most of your comments. Would you prefer that I commit those directly on this branch or send you edits so that you can incorporate? I'm guessing the former, but wanted to make sure.
I might need a bit more guidance on this point. It sounds like this would mostly be configuration of RTD? I'm happy to be added, but I'm pretty sure I'll have you drive the RTD side of things. I've just signed up on RTD using my Github credentials (username: grovduck). |
The former would be great, thanks! I'll co-assign you :)
Perfect, I invited you as a maintainer. There shouldn't really be anything either of us need to do now that it's set up - in my experience with past projects, I only ever have to visit RTD if the docs build fails for some reason, and anyone can access those logs. But I'll feel a little better knowing you have admin access if needed! |
|
Sorry, I found a few mistakes that I had put in with my edits, so I've fixed and committed those. |
Co-authored-by: Matt Gregory <matt.gregory@oregonstate.edu>
|
It feels like you're getting really close on this one. I think I've responded to all the outstanding issues/questions but let me know if I've missed something. Otherwise, LGTM! |
I just realized this is possible! No longer need to worry about keeping the numbering consistent when footnotes are added/removed.
Co-authored by: Matt Gregory <matt.gregory@oregonstate.edu>
|
Looks like everything's resolved, so I'll go ahead and merge! |
|
The docs are live! Good teamwork getting this one put together! https://sknnr.readthedocs.io/en/latest/ Unfortunately/unsurprisingly the absolute links to the docs in the README are broken, but that'll be an easy fix at least |
This would close #5 by setting up documentation for
sknnrusingmkdocs.@grovduck This might be a little premature, but I was excited to try out
mkdocs(big fan so far!), and I figured having the docs in place will make things easier once we start digging into #10. I'm considering this an early prototype, as there's still tons of room to adjust the layout, visuals, and (especially) content.I moved the developer guide into
docs/pages/contributing.mdand added some documentation-specific info there. The most important thing is to runhatch run docs:serveto start a live-reloading server where you can preview the docs.Guides
This uses mkdocs for the core functionality, mkdocstrings to generate the API reference from docstrings, and mkdocs-material for the theme, which adds a lot of nice additional functionality. The mkdocstrings guide details the features and some of the config options for generating the API reference. I suspect once we start getting more complete docstrings, it may become more apparent how we want to set that up. The mkdocs-material config guide has a lot of info on customizing the site appearance and functionality. The mkdocs config guide also has some good info on markdown extensions and plugins that might be of interest. I definitely haven't done a comprehensive read through any of those guides, so if you find anything cool that's worth adding, feel free to make changes!
Content
I wanted to rough out the content just to give us a starting point, but as the domain expert I'm hoping you can rewrite and flesh things out as needed. Feel free to modify anything I wrote! My assumption is that this is being written for an audience that's already familiar with
sklearnso we don't necessarily need to dive into the technical basics, but I'm not as sure about how much detail on the stats to include. I don't think it would hurt to discuss how the estimators work, but we could also just point to the relevant papers.ReadTheDocs
You can see the RTD build for this PR here, and it should update whenever we push a new commit. Once this gets merged into main, RTD will build that and we'll have a stable docs page. You can track build status here. Currently I'm the RTD maintainer for the project, but if you want to create an RTD account (I just login with my Github), I can add you as a maintainer, which would allow you to manually trigger builds and access project settings.