Add a complete session auth example to the docs about piccolo_api

[sinisaos]

@dantownsend I'll do it in a few minutes.

[wmshort]

Excellent -- this is very helpful. Would it be possible also to give an example of how the CRSF token mechanism is supposed to work? Thanks

[sinisaos]

@dantownsend Do you think of the whole app as in the Piccolo examples? If not your example from comment is perfect example of SessionAuth and that should be in docs.

[dantownsend]

@sinisaos The example code here might be sufficient.

I was thinking of a new page in the docs, with this code in it.

The example code is an abbreviated form of one of my own apps - I haven't actually tested it standalone, but it looks correct.

What I'd love is if we had a new folder in the repo called examples. This file would be in there, and we'd somehow embed it within the docs.

I know Sphinx can be used to embed fragments of files, but I haven't tried embedding an entire file before.

At some point, we could add a unit test for the example app, to make sure it works.

[sinisaos]

@dantownsend I have a question. I don't know anything about Sphinx's embed fragments of files, but I created a Piccolo Task starter app (based on your example) with SessionAuth where openapi docs are private and the home page is public. Everything works great, but I don’t know if I need to push the app to my Github repo and then you can put a link in the Piccolo examples or what to do with it? Thanks in advance.

[dantownsend]

@sinisaos I think it would be nice to embed the code directly in the docs.

I've figured out how to embed entire Python files:

Full example
============

.. include:: example.py
    :code: python

[dantownsend]

If you wanted to push your code to a new repo, I don't mind linking to it from the piccolo_examples repo.

But I'd still like to embed an example in the Piccolo API docs.

[dantownsend]

Thanks for checking the example code works.

[sinisaos]

@dantownsend I made examples folder in SessionAuth directory in docs and then embed with

Full example
============

.. include:: ./examples/example.py
    :code: python

Result is:

Did you mean something like this or?

[dantownsend]

@sinisaos That's right - but can we put the example in it's own page?

[sinisaos]

@dantownsend Yes we can.
Index page

Full example page

[dantownsend]

@sinisaos That's great, thanks

[dantownsend]

If you open it as a PR, I'll get it merged.

[dantownsend]

Fixed by #86