search

caleb531 / automata

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

Divide API documentation into multiple files #98

Closed caleb531 closed 2 years ago

caleb531 commented 2 years ago

@eliotwrobson @Tagl

Currently, the API documentation in the README is massive and monolithic. It potentially hides the presence of certain features because there is so much to scroll through, and it can make the documentation more overwhelming for newcomers. Sure, there's the Table of Contents, but it is not as easily accessible from any one section (i.e. scroll to the top of the page, then down a bit).

I'm thinking of moving all API documentation (including the TOC) to a new docs/ directory in this repository. It would still all be Markdown, just broken up across multiple files (mostly mapped to the current TOC links).

To ease access from one page to another, I'm thinking of including a link to the TOC at the top and bottom of every documentation page/file. We could also add Next/Prev links (on DFA docs: "Next Up: NFA class"), but this could become cumbersome to manage.

A prerequisite of this reorganization would be to close out all existing PRs that touch the README in any way. I'm creating this Issue to give you guys a heads-up of my intention, and also to solicit feedback.

Tagl commented 2 years ago

I believe there's also a Wiki functionality on github that could be used.

caleb531 commented 2 years ago

@Tagl That's true, and GitHub Wikis may provide a nicer experience browsing the documentation. However, the experience for submitting updates via PRs appears to be a bit involved. And, from what I'm reading, almost feels like the wiki is a pseudo-repo of sorts in order to maintain a connection with the main repository.

caleb531 commented 2 years ago

@eliotwrobson @Tagl Alrighty, I've merged all open PRs, so the documentation reorg is next on my list. Please don't submit any new PRs until I finish that work and merge into develop.

caleb531 commented 2 years ago

@eliotwrobson @Tagl Merged the reorganization into develop, so you guys are clear for any new PRs you want to submit.

Closing this issue.