Documentation site rework #189
Conversation
* Changed excludes * Started adding docs for DFA class
|
@eliotwrobson Thanks for all your efforts to put this together! I won't be able to review today, but will probably take a look sometime during the week. |
|
@caleb531 sounds great! I think most things from the old docs have been ported into the new site successfully. The main thing is making sure we have everything required to pass the review. It's OK to have things be a little barebones, since I think we will get some good suggestions for things to add to the docs from that review. Once this is merged, I think the course of action will be to set up a publishing workflow, then merge to master to hopefully deploy the new site. Then, with the changes to some of the other repo files, we should be good to go with a full submission! cc @lewiuberg since you did the initial work on this. |
|
@caleb531 do you have some time to take a look at this soon? I don't think this needs a super detailed review since I know this is huge, but as long as it's at an MVP stage, we'll get additional comments from the PyOpenSci review that should iron out any remaining issues. |
|
@eliotwrobson Yep I can take a look tonight, but if it's ready for my review, shouldn't we take this PR out of Draft Mode? |
|
@caleb531 yep! Good call, I forgot to take this out of draft when I added the rest of the documentation. |
|
@eliotwrobson Reviewing this now! Can you please remind me how I can run the documentation site locally? Do we have that documented somewhere (perhaps in CONTRIBUTING.md in this PR)? |
|
@caleb531 the commands are in #160, last three commands here: #160 (comment) |
|
@eliotwrobson Oh yes that's right, I have actually run this before 😅. Thank you! Reviewing now... |
There was a problem hiding this comment.
@eliotwrobson I've finished my review! I tried to keep my comments few and focused. I think the biggest thing would be solving the 404 when you land at the root of the documentation site, but as I've found, that should be easily fixable.
Thank you for all the time you've put into this (and you too, @lewiuberg)!
Co-authored-by: Caleb Evans <caleb@calebevans.me>
|
@caleb531 addressed all of your comments! If it looks good and you approve, I can go ahead and merge, and then I'll try and work on a deployment workflow as part of a followup PR. |
|
@eliotwrobson So I guess I was looking at a cached version of the docs site, because I just hard-refreshed, and the theme is way better. The sidebar is also always-visible, which I remember specifically requesting. All that to say, this docs site is looking really great, and I am totally onboard now. I think the search functionality will be much appreciated as well. 
|
There was a problem hiding this comment.
@eliotwrobson Okay, all conversations are resolved, so I'm ready to move this forward. Approved!
Please feel free to merge when you are ready.
|
@caleb531 Awesome! I'll merge this now and get to work on the workflow later this afternoon. |
Draft PR for the new documentation site. Docstrings have been added for all functions in the public interface, and the mkdocs site now generates the API from these docstrings.
@caleb531 still some polishing to go, including porting over examples, but there's enough here that it's probably worthwhile to start reviewing. In response to #160.
For reference, as we are submitting the package to PyOpenSci, here is their guide on writing package documentation: https://www.pyopensci.org/python-package-guide/documentation/write-user-documentation/get-started.html
For this review, we should make sure the new docs site specifically address all of the items in the guide.