Welcome!
This is the community forum for my apps Pythonista and Editorial.
For individual support questions, you can also send an email. If you have a very short question or just want to say hello — I'm @olemoritz on Twitter.
Documentation Examples
-
@omz, look really, I think your documentation is really good. However the examples could be better. I would say a lot of the examples are not easy for a beginner to understand. I understand it's a balancing act. I have still been having problems with ui.ImageContext. I wanted to draw to the screen but sometimes I wanted to get an image of what was being drawn to the screen. Drawing to the screen is documented as well as creating a image is documented. But I really struggled how to do both. For a seasoned Python programmer, I guess this is so trivial it's not funny. But for me it wasn't, I can't be the only one that struggles with examples given in a very small context. Yes Blah blah blah...😱
I am coming to a point....
I don't think the documentation should be changed. I think as you get better and better you appreciate the concise way it's written and layed out.
But one idea, a new chapter of examples. Better still if there was a link from the topic in the main help file. These examples could be user submitted. I know there are sources to get the info. But it can be tedious to find what you are looking for. In the long run, I am sure this would save you a lot of questions also. Simple code samples for a working table with a datasource and delegate, defining custom ui.Views. I know it's there, but it's sort of there. You need to connect quite a few dots as a beginner to get it.Look it's just a idea or beginning of a idea. I was so frustrated I could not work out how to draw to the screen and then if I wanted to get the same image as a image and display it as an image or save it. In my infinite wisdom I was trying to conditionally create a ImageContext with in the draw method. Huge Fail. Just have to remember, what comes naturally to you and others that know Python so well does not immediately come to all of us.
My example is below. Not sure I have done it right or not. I think I have. I separated the draw cmds into a separate method. So I didn't have to do something like ui.set_needs_display to get it to render. But if what I have done is semi correct, you can see a big disconnect from the examples in the documentation to what would be considered functional.
import ui class DrawSomething(ui.View): rect = (0, 0, 200, 200) def draw(self): self.my_draw() def my_draw(self): with ui.GState(): ui.set_color('deeppink') shape = ui.Path.rect(*self.rect) shape.fill() def image_get(self): with ui.ImageContext(self.rect[2], self.rect[3]) as ctx: self.my_draw() img = ctx.get_image() img.show() return img def image_save(self, path): img = self.image_get() with open(path, 'wb') as file: file.write(img.to_png()) if __name__ == '__main__': ds = DrawSomething() ds.present('sheet') ds.image_get() ds.image_save('test2.png')
-
@omz
I think it would be a great idea to publish the documentation on GitHub, thus allowing the community to change descriptions or update outdated examples.
(I'd love to write some examples and documentation for theevernote
module.)Also, I don't know how documentation is structured internally (i think it's html files), but it'd make sense to have - unless it's absolutely impossible - documentation for both Python versions in the same file.
For most modules, the Python 2.7 and 3.5 version consists of roughly the same set of functions/attributes. You could just hide the parts that don't apply to the currently selected Python version. This'd also fix the problem that changing the Python version for coeumentation will return you to the homepage. -
There are also still multiple errors in the documentation:
objc_util
- Now playing example
- Missing import
ObjCClass('NSBundle').bundleWithPath_('/System/Library/Frameworks/MediaPlayer.framework').load()
- Old
print
statement in Python 3.5 documentation
- Missing import
- Send E-Mail example:
mail_composer.setDelegate_()
instead ofmail_composer.setMailDelegate_()
- Now playing example
ui
ui.WebView
Delegate examples are missing theself
parameter
(There are more examples but that's all I've been able to find right now)
-
@lukaskollmer I think @omz has said in the past that the documentation's build system is a mess, etc. and he therefore wants to wait a bit before publishing it.
-
@Phuket2 I absolutely agree that the documentation could be better in a lot of places. As you mentioned, it's sometimes difficult to balance the needs of experienced users (who want concise info) and beginners (who might be more interested in tutorial-style documentation). I will also admit that writing documentation is not my favorite part of development, although it is very important of course.
In a couple of modules, I've tried to integrate little tutorials and examples in the "introduction" part, but I realize that's not always ideal because you kinda have to know which module you're looking for to even find that info...
Putting the documentation on GitHub is definitely something I'm considering, though it's also important to keep a consistent style throughout the docs, and that might not work well with multiple contributors. There would also need to be a way to update the documentation within the app for this to really make sense, and that leads to various other questions (where to host the downloads etc.). In general, the documentation system in Pythonista 3 is better prepared for such a thing (the entire documentation is essentially just a Zip file now), but it would still require quite a lot of changes in the app to actually make this work.
Long-term, I have a couple of other ideas, beyond the reference documentation, that could make Pythonista more useful as a learning environment for beginners, but that's for another time.
PS: Did you get my direct message on Slack?
@lukaskollmer The documentation for Pythonista's custom modules is currently exactly the same for Python 2 and 3, but the standard library docs are quite different.
-
@omz what about...
"For more examples, explanations, tricks, and tutorials click here for Pythonista Community Notes" link that just opens an external site with this collaborated documentation? (In the meantime) -
@cook there is already a link to the forum in the app.
Also, I don't think having two different official documentations it a good idea.
-
@lukaskollmer yes I agree it's not ideal to have separate documentation.
A link to forums is good but one can easily get lost looking for something specific- and then needs to ask questions.
Linking to more thorough documentation is done in the bs4 module. I think this isn't bad!
Ideally I would hope for it to be in one place- but if you're having collaborative documentation and it's updated, then it would also require an app update.
I guess there are positives and negatives either way...
-
@omz , as I say I think you have don't a great job anyway. For what you pump out its like there are 10 of you working on this.
I totally understand your concerns about making the documentation public. I used to think it would be a great idea, but the reality I think is that it could take you more time to proof read edits and check styling than it would be to do it yourself. I am just guessing, but maybe there are some kick ass editors out there these days that reduce this issue significantly.
My comments here is more to have an appendix of user submitted examples. Or let's say a virtual appendix. Of course an appendix like this should be separate from your normal build.Actually, I do understand how difficult help files/documentation is. But from a different way. The big product I was in charge of was a vertical market product. The automotive industry. 20 years ago cost us approx 10,000 usd per help file to be translated by Xerox. Just the help file, not the interface. When I left the company we had over 20 languages in application. So you can imagine every single change needed a shit load of paper work. Actually, I said languages. It was languages and regional information, back then the OS gave you minamal support. Just saying, I understand the complexities. At that time we dropped shipped 40,000 CDs/DVDs from Sony plants around the world every single month. No room for error.
But all said and done omz, you seem to have a good handle on this. I don't want to kiss your ass, but as a indie programmer you are killing it. Really, I am so impressed. Not that's important, just is to me.
-
@omz: You could publish the documentation on GitHub, but accept only PRs for minor changes (fixed typos, updated code examples, added explanations for undocumented function arguments or return types, etc)
This would also make linking to the documentation easier. Right now, If i want to link to a specific part of the docs, I have to find the correct documentation page on the website, go to the page source and find the id of the function/class I want to link to.