[WIP] Add developer-facing documentation (user-facing docs to follow) #1174
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Member
|
|
sammdot
force-pushed
the
doc
branch
4 times, most recently
from
85b050f to
219582f
Compare
Member
|
Parallelly, some typing stub files (for mypy type checking for example) would also be useful. |
This allows us to properly organize user-facing as well as developer-facing documentation when we add more in the future.
Details can be filled in as needed, but this is a fairly comprehensive list of constants, functions, methods and classes that either can be called or will need to be implemented by plugin developers.
This page only talks about Plover-specific items like the entry point system and integrating with the Plover API, so we offload the general packaging stuff to the official docs.
This is pretty much copied from the existing wiki, with some changes regarding macOS 11 Big Sur, since the pre-built Plover binaries don't currently work on this platform and will have to be built from source. This grouping also allows me to split up the docs into a "quick start" for people who just want to use Plover as-is, and an advanced usage section involving things like plugins and non-English systems.
|
|
||
| ```ini | ||
| [options.entry_points] | ||
| plover.gui_qt.machine_options = |
There was a problem hiding this comment.
I was following this guide, and found that I needed to use this instead:
Suggested change
| plover.gui_qt.machine_options = | |
| plover.gui.qt.machine_option = |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary of changes
This pull request adds more developer-oriented documentation to the
doc/directory, primarily consisting of plugin development docs (based on the plugins wiki page) and an API reference (not currently documented). I believe the ideal place for documentation is adjacent to the code it's for, but I'm not sure how y'all feel about docstrings and type annotations directly in the code so I think this is the next best thing.I've set the repository up for Read the Docs (https://readthedocs.org), which provides documentation hosting free of charge for a public repository like this one. The documentation on that site is updated for every commit, so there's no need to worry as much about keeping it updated.
My WIP branch is currently hosted at https://plover.readthedocs.io/ using my personal account, though of course I'd be happy to hand over ownership of the RTD project when this gets merged. Eventually I'd like for it to be hosted at something like https://docs.ploversteno.org/.
In the future, I'd like for this site to contain much of the user-facing documentation that is currently in the wiki as well -- installation instructions, hardware options and setup guides -- but my priority right now is the developer docs since that is currently not as complete.
Pull request checklist