Introduce mkdocs for API documentation #31
Conversation
lognaturel
force-pushed
the
mkdocs
branch
2 times, most recently
from
623babe to
5559733
Compare
|
I'd be interested in your high-level thoughts @lindsay-stevens. I believe this will make the library a lot more accessible so I'm eager to get it in. If you have some cycles and can take on the couple of todos at the top that would also be wonderful. Something else I think we should add are recommendations for error handling. I believe all error states result in exceptions and most provide the raw error message from Central. It would be helpful to document that and I think the info on logging that's in the readme now could be moved to that section as well. I think you're best positioned to write a bit about that. |
But your high-level feedback is the most important thing and I can take those todos! |
|
Hi @lognaturel looks good! I haven't used mkdocs so it took a little bit of digging in the docs to get up to speed. I opened a PR in your fork with some suggestions. About the todo items, I don't have privileges to enable Pages on this repo. But it looks like there's a script on:
push:
paths:
- 'docs/**'
- 'README.md'Also I was wondering re: docs if it might be interesting to show a version of app_user_provisioner.py as written using projects.create_app_users(). |
|
Thank you! Hoping I can come back to it near the end of the week.
I don't think it should just be a version, I think it should be a replacement! |
|
@yanokwa has requested that I explore doing these docs within https://github.com/getodk/docs so we have more overall consistency. |
|
I don’t see a great short-term path to a more integrated docs experience. I’ve discussed with @yanokwa and we’re going to start with this so there’s at least some easy-to-use documentation. We can iterate and redirect as needed. |
|
I had to remove |
- mkdocs pulls in ~75 deps on top of dev's ~25 so separate them to try to avoid dependency issues.
- explicitly name the docs pages to try to make it clearer that forms/subs/projs
are attributes of the Client. As main sections they seem like they're separate
classes or topics. Nesting these into a collapsible section seems unnecessary
because currently they are a main purpose of the documentation.
- move the header documentation in projects, forms, submissions into the classes
since it is useful info for docstrings to have.
- while it may be possible to use a script to avoid having the remaining stub
files with autodoc instructions, it seems unnecessary for only 4 files.
- add docstrings for Client.open / close so that they show up in the docs.
- README:
- fix indentation of the Client methods list, it didn't render properly.
- add section on "Errors raised by pyODK".
- remove relative links to Examples library for now because it won't work
on both GitHub and rendered docs - replace later with links to the published docs.
- move README.md in project root, so it is in the most obvious place.
- add explicit mkdocs "watch" item to ensure README changes trigger reload.
- add "index.md" with a snippet instruction, to copy over the README content.
- add ODK logo
- svg minimised: removing some raster shadowing around the border cuts the
file size from 128KB to 2KB. Imperceptible difference at the size it's rendered
at, particularly with a dark background.
- add basic light/dark mode.
- add repo url/name to link to GitHub
- sort the theme/features and mkdocstrings/options dicts for legibility.
It's helpful to have reference for available functionality in a nicely-rendered way.
Remaining to do:
What has been done to verify that this works as intended?
mkdocs serve, looked at the resulting docs.Why is this the best possible solution? Were any other approaches considered?
My goals for this were:
Overall, I'm really happy with
mkdocsandmkdocstrings. This was straightforward to put together and I think it looks nice. Unfortunately, it doesn't fit in with the styling of any of our existing docs. I think we can deal with that separately.How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?
No change to code.
Do we need any specific form for testing your changes? If so, please attach one.
No.
Does this change require updates to documentation? If so, please file an issue here and include the link below.
This is the change to documentation.
Before submitting this PR, please make sure you have:
testsnosetestsand verified all tests passpython bin/pre_commit.pyto format / lint code