-
Notifications
You must be signed in to change notification settings - Fork 46
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
No Documentation? #27
Comments
README seems to contain details like: Are you looking for specific help? |
What @mandarvaze said. I've seen far too often documentation getting out-of-date, so for this project I rather invested (far) more time into providing several runnable examples that contain lots of comments and tests to showcase how to use the library. These examples are all tested on CI that makes sure they don't get out-of-date. That said, I do plan to add a page or two of narrative documentation, but I need to decide first how I want to do it because I'd want any examples in this documentation to also be testable. Finally, if you can tell me what you think is missing the most from the current README and examples, I'd gladly address it. |
We have a few doctests in Pyramid as examples, which includes |
Thanks! I've done this in the past with Plone too: https://github.com/plone/plone.api/blame/master/docs/user.rst#L24 It's mostly that I've kinda grown bored of writing .rst and really enjoy writing .md files these days. I'd possibly like to try doing the above with .md. Maybe. Not decided yet. :) |
If you are interested in writing documentation in .md, mkdocs might be a good alternative. |
@damonhook does mkdocs run Python tests? I found it limiting. @zupo have a look at MyST. According to its docs, you can write markdown and do everything that you can do with reST in Sphinx. @pauleveritt is a fan. |
At base no, but mkdocs relies heavily on extensions and plugins to get these kinds of functionality. While I have briefly used recommonmark before, I have not seen MyST. Skimming through the docs it does looks promising and sounds like it may be a better fit here. |
@stevepiercy: MyST is exactly what I had in mind, thanks for the link! |
@zupo I've got an itch to scratch for trying out MyST and writing docs for pyramid_openapi3, as I run through the sample apps. Do you have an outline for docs or a brain dump of topics that you would include? The readme is fairly comprehensive and I don't see anything obvious missing, except a reference to auth. I could do the heavy lifting if you point me in the direction you'd like to see this go. |
Oh wow, that would be great! I don't have strong opinions. I've tried to start writing docs myself in the past and couldn't really decide where to start because almost everything is already in Readme. That said, some advanced techniques/featuers/tricks are not in Readme. So maybe a simple "howto" section followed by "advanced features"? The only opinion I have is that I would strongly prefer if most (if not all) code blocks are tested. I've achived this for Plone API docs using |
OK, that sounds good to me. A pyramid_openapi3 cookbook! I would like to avoid duplication of the readme to reduce maintenance. IMO a readme should be minimalist, directing the audience to where they should go for more information. Do you have a strong opinion about what should remain in the readme? |
|
Where can we find documentation for this lib?
The text was updated successfully, but these errors were encountered: