search

cloudstateio / python-support

User Language Support for Python
Apache License 2.0
7 stars 5 forks source link

Antora Documentation for Event Sourcing #14

Open marcellanz opened 4 years ago

sleipnir commented 4 years ago

will we add the documentation to the Cloudstate repository or do we do it here in this repository and then add the links there? I think @pvlugter had this open discussion

marcellanz commented 4 years ago

I expect it to be on the repo as suggested by Peter. I don't know yet how it will work to be separated from the main repository and how/if it gets integrated into the main documentation.

pvlugter commented 4 years ago

Yes, would be good to have the docs in each repo. There are some things to set up for this. I expect that we'll start with something simple, where each language support can publish docs into the main site as needed (it won't be one navigation tree for the docs though, separate doc sites, like for akka modules). I'll try to make some progress this week. For now, feel free to just add into the main documentation, and then we move later.

marcellanz commented 4 years ago

PR #35 adds a starting point to have user documentation within the user language support.

chomnoue commented 3 years ago

@marcellanz should I pick this to complete the documentation? Or are you working on it?

marcellanz commented 3 years ago

@chomnoue please pick it and use it. I do not work on it right now and I hve no progress othr than I merged Peters PR. Thanks for picking it up :)

pvlugter commented 3 years ago

@chomnoue, how's it going with the documentation? Would be great to have the docs up so we can include Python support as available.

sleipnir commented 3 years ago

Hello @chomnoue @marcellanz if you are very busy and are having trouble including the documentation I would be happy to help you with that. If you want I can start a draft of the documentation and formatting. What do you think?

marcellanz commented 3 years ago

I let it @chomnoue to decide, the Go docs can be used to start and get structure/configs/refs.

sleipnir commented 3 years ago

Thank you @marcellanz , yes I believe he has the answer. At this point I think that any of the repositories that are already in the standard can serve as a base. Can you ping him somewhere? I believe that he hasn't seen the github lately.

marcellanz commented 3 years ago

@sleipnir I've asked Alain-Michel on chat. Let's see what he is on and then decide what to do.

sleipnir commented 3 years ago

Thanks @marcellanz

marcellanz commented 3 years ago

I think we might go ahead if with the issue if it's preferred to have documentation to get started with event sourcing. There is a branch which @chomnoue has started. I was not able to reach @chomnoue through chat (Gitter). I also did not see other progress on a branch on Alain-Michels account other than the branch mentioned above.

@sleipnir if you like to help I'd propose to go on with the documentation branch that exists. We could review the documentation together also if Alain-Michel likes to join we'd have even more eyes on documentation properly written for Python.

Regarding documentation review and experience with the API, I've seen that @sean-walsh mentioned on a Lightbend podcast his work with the Python Cloudstate support for a talk at EuroPython he gave. It would be nice to get some feedback from his side about his experience with the Python API too. We pushed v0.1.1 especially because of the nice Introduction Adriano did for the projects front page on PyPi.

sean-walsh commented 3 years ago

Hello, the talk went well, I'm still trying to get some statistics on it. I've gone over the Python example code again since. I had some personal confusion that turned out to be about Python conventions, once I got my head around it, the code seems more straight forward. One minor question, is it convention not to indent the members of a class? That and the multiple whitespace lines in this file confused this java developer at first.

https://github.com/cloudstateio/python-support/blob/master/shoppingcart/shopping_cart_entity.py

edit: I now see these aren't really member functions so please disregard. I answered my own question.

marcellanz commented 3 years ago

Thank you for your feedback and insights. I'm looking forward to catching up with the talk once online.

While using that many blank lines between definitions seem to be normal by the "PEP 8 -- Style Guide for Python Code":

Surround top-level function and class definitions with two blank lines.

and even more blank lines can be used sometimes, the non-intended members are no members at all, and I have to ask @sleipnir or @chomnoue why the shopping cart is implemented that way.

sleipnir commented 3 years ago

Hi! @marcellanz @sean-walsh As the extra lines can be used sparingly to separate logical associations, I think that was an intention. But we can remove and work with just a blank line to return functions.

Marcel, I'm going to take a look at the documentation branch and try to continue from there. Obviously we will review together, the more reviewers the better

sean-walsh commented 3 years ago

If the blank lines represent the normal convention it's fine.

sleipnir commented 3 years ago

I vote to remove them

marcellanz commented 3 years ago

I'd vote to retain them.

Linters (pycodestyle, pep8) and as an example PyCharm by default use 2 blanklines between top-level functions. Why would we remove them when it's recommended by the python style guide?

If we mandate any formatting and style by th eproject, I'd propose to add a formatter/linter that formats the code, same as we use scalafmt or go fmt. We'd have to argue a good case for deviating from PEP8 or anything settled as a standard I think.

(this is one thing I really like with Go, there is no discussion when it comes to formatting Go code :), not that I dislike any discussions about style)

> pycodestyle shopping_cart_entity.py
...
shopping_cart_entity.py:81:1: E302 expected 2 blank lines, found 1
...
>
Screenshot 2020-07-29 at 18 12 34
viktorklang commented 3 years ago

I think each example should be idiomatic for its language. Formatting included. -- Cheers, √

sleipnir commented 3 years ago

I'd vote to retain them.

Linters (pycodestyle, pep8) and as an example PyCharm by default use 2 blanklines between top-level functions. Why would we remove them when it's recommended by the python style guide?

If we mandate any formatting and style by th eproject, I'd propose to add a formatter/linter that formats the code, same as we use scalafmt or go fmt. We'd have to argue a good case for deviating from PEP8 or anything settled as a standard I think.

(this is one thing I really like with Go, there is no discussion when it comes to formatting Go code :), not that I dislike any discussions about style)

> pycodestyle shopping_cart_entity.py
...
shopping_cart_entity.py:81:1: E302 expected 2 blank lines, found 1
...
>
Screenshot 2020-07-29 at 18 12 34

I thought you were referring to the spaces at the end of the functions

marcellanz commented 3 years ago

We might have misunderstood each other :)

We speak about the "two blank lines" surrounding top-level function and class definitions IMO. shopping_cart_entity.py has no other blank/whitespace lines I think?

Lines 73 and 74, and 80 and 81 here:

Screenshot 2020-07-29 at 20 13 38
sleipnir commented 3 years ago

Okay. If we use an appropriate formatting tool this will not be a problem anymore.

marcellanz commented 3 years ago

@sean-walsh @sleipnir @chomnoue the video of Seans' EuroPython 2020 talk dropped today: https://youtu.be/Swl9tUnGGGE?t=6695 Cool stuff :)

marcellanz commented 3 years ago

@sleipnir can you remember why handlers were implemented as non-member functions. see also https://github.com/cloudstateio/python-support/issues/14#issuecomment-665714059 above.