search

caleb531 / automata

A Python library for simulating finite automata, pushdown automata, and Turing machines
https://caleb531.github.io/automata/
MIT License
348 stars 64 forks source link

Documentation site rework #189

Closed eliotwrobson closed 10 months ago

eliotwrobson commented 11 months ago

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.

coveralls commented 11 months ago

Coverage Status

coverage: 99.64%. remained the same when pulling c62d3ea4c12dab5f98571b0e311753b3d27f08f2 on docs_rework into fa2a6ece19f27bb7e0a2d54b0c672bc5a8f272ad on develop.

caleb531 commented 11 months ago

@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.

eliotwrobson commented 11 months ago

@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.

eliotwrobson commented 10 months ago

@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.

caleb531 commented 10 months ago

@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?

eliotwrobson commented 10 months ago

@caleb531 yep! Good call, I forgot to take this out of draft when I added the rest of the documentation.

caleb531 commented 10 months ago

@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)?

eliotwrobson commented 10 months ago

@caleb531 the commands are in #160, last three commands here: https://github.com/caleb531/automata/issues/160#issuecomment-1615259047

caleb531 commented 10 months ago

@eliotwrobson Oh yes that's right, I have actually run this before 😅. Thank you! Reviewing now...

eliotwrobson commented 10 months ago

@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.

caleb531 commented 10 months ago

@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.

Screenshot 2023-12-29 at 10 06 28 AM
eliotwrobson commented 10 months ago

@caleb531 Awesome! I'll merge this now and get to work on the workflow later this afternoon.