No Documentation?

[phrfpeixoto]

Where can we find documentation for this lib?

[mandarvaze]

README seems to contain details like:

• Getting Started
• Link to Sample App

Are you looking for specific help?

[zupo]

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.

[stevepiercy]

We have a few doctests in Pyramid as examples, which includes testsetup. Example:

• https://github.com/Pylons/pyramid/blame/0bdc83690cdd11a7044c8106e8fd84bf2df46d95/docs/narr/hooks.rst#L309

[zupo]

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. :)

[damonhook]

If you are interested in writing documentation in .md, mkdocs might be a good alternative.

[stevepiercy]

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

[damonhook]

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

[zupo]

@stevepiercy: MyST is exactly what I had in mind, thanks for the link!

[stevepiercy]

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

[zupo]

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 invisible-code-block (https://raw.githubusercontent.com/plone/plone.api/master/docs/portal.rst) and it really worked well -- most docs errors got caught by the CI when upgrades/changes to library code happened.

[stevepiercy]

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?

[zupo]

• https://github.com/Pylons/pyramid_openapi3#advanced-configuration should go out and into docs
• https://github.com/Pylons/pyramid_openapi3#demo--examples could probably be rewritten with more narrative text around the code samples, as chapters in the docs
• https://github.com/Pylons/pyramid_openapi3#design-defense can go out and into docs too
• https://github.com/Pylons/pyramid_openapi3#design-defense can go out and into a "Contributing" / "Developing" section of docs
• https://github.com/Pylons/pyramid_openapi3#design-defense can probably be moved too