Another New Guy

Introductions
#1

Hi, my name is Logan.
I’m a fullstack software developer at AIG in Houston. I work primarily with Javascript but we also use Java with Spring Boot on the tail end.

I’ve been programming in Python for a few months now. I’ve recently picked up the language and I love it. It feels like a more ‘professional’ Javascript (but you’ll never see me tweet that).

Currently, I am using sanic to power my REST APIs. I’ve come to the community after listening to the most recent Talk Python podcast and I’m here to learn and help. I’ll write docs, tests (we have a huge coverage push at AIG right now), and fix bugs. I’m relatively new to python open source, but this is a project that I’d love to help keep moving.

1 Like
#2

Nice to have you around Logan :grinning:

You may not tweet it … but you put it online … so, maybe I will :wink: Joking aside, I use Javascript everyday at work too. There are some things in the language that I really enjoy. But, it should come as no surprise that Python :snake: is my language of choice.

I think documentation, examples, and testing are the three easiest wins.

We currently have no good way of aggregating examples, but I really would love to get some more use cases to highlight how people are solving problems with Sanic. Hopefully we will come up with a strategy for a proper front page (as opposed to what is on sanicframework.org right now), and perhaps a way to show.

As for testing, I really would like to push our test coverage. So feel free to jump in there!

Glad to have you aboard!

Welcome to Python and Welcome to Sanic.

#3

Thanks! I’m glad to be here. Yes, I enjoy Javascript, but the more I work with Python, the more excited I am about it. Its becoming my ‘thinking’ language. :slight_smile:

When you say, no good way to aggregate examples, what do you mean?

#4

One thing that is lacking is a good set of tutorials, examples, and best practices. I’m thinking this is the sort of stuff that should go on the main website.

How to connect to a DB? Send emails? Run websockets (the current page in the documentation is too basic)? Run automated testing? Setup a file structure?

We need some good way to capture this kind of content to make it helpful and accessible to anyone that wants to test out the waters.

#5

This is a great idea. I like examples and I’m a pretty big architecture nerd so I’d love to take it on. After the new docs enhance goes through, I’ll look into building docs.

Do you have favorite docs? I think the React documentation is incredible and (to me) is the golden standard for documentation.

#6

Do you mean platform, or project?

I definitely like using mkdocs where appropriate. And while I am not a fan of material design, and am getting tired of seeing it everywhere, I do really like the mkdocs-material theme.

#7

If you’re the type of developer who likes to read good docs, but doesn’t like to write good docs, you can skip this.

IMHO there are two species of docs:

  1. One pagers, (the short story) with few to zero external references. (eg a man page) Markdown and Mkdocs are good for those.

  2. Encyclopedic: multi-volume, multi-version with cross references and conditional content. (eg. the Dango project) FWIW, my gold standard for docs is the Django project:
    https://docs.djangoproject.com/en/dev/internals/contributing/writing-documentation/

Python is unusual in that the compiler provides a lot of content for documenting code, so in many cases you just need to add a little color commentary, such as the requests api docs

#8

You are correct, and I agree with you. There’s the “how can I do something”, and then there’s the “what can I do”. This is exactly what I would love to get for Sanic at some point. But, it is a LARGE effort, and will take some time and planning among a group of people.

We have the RTD going now, and I think that is fine and familiar for now. What we are missing is what you are calling the “encyclopedic” reference that incorporates the walk-thru style, with working examples, etc. I think this is content that would be more fitting to be hosted at the main website (sanicframework.org), when we get the energy up to properly build that.

If you are throwing your hat into the ring to join that effort, then I say “welcome aboard!”

#9

A few years ago I implemented a private instance of readthedocs. It is a beast of an application! Sphinx wrapped in Django, redis, celery and sprinkled with Oauth. Kudos to the team that makes it look so simple to the outside.

I think this project should be fine with Sphinx and the built HTML can be hosted anywhere you like.

#10

Do you have favorite docs?

I mean - do you have docs that you absolutely love?

Maybe - Boostrap docs instead of material?

I think good documentation clearly outlines the average use-case while also having documentation to deal with edge cases and having that ‘encyclopedia-like’ feel to them.

Java’s docs are actually pretty good too, when it comes to their exhaustiveness.

I’m starting to see what you mean though. Especially with what @blaisep mentions - It would be good to have examples of Celery, Redis, Django, and OAuth examples. Do you think it’d be good to include them in docs form (attached to the documentation)? Or create a repo and link to the example?

(jeez. How many times can someone say docs in a conversation?)

PS - As a professional frontend developer, I’m more than happy to start talking client-side solutions. When React is an option, every problem is a nail. :sunglasses:

PPS - ^ joking about above. And yes. That material theme looks really clean.

1 Like
#11

I think we are able to start getting into some substantive questions here about building documentation and a front end. Let’s open up a new conversation for this. Feel free to start one here before I get a change to (probably not until late tonight).

Documentation and Frontend Rejig
#12

I always see the SQLAlchemy’s documentation to be one of the best examples on how to use automation to give you almost everything, from your docs to the code itself. The pydocs (example) on the source are the real killers IMO.

#13

I totally agree. This makes it easy to go over the implementation related details while getting the exact idea of how and why to use certain API in a certain way. Since sphinx support validating these codes, we can ensure that they are kept up to date with any change in APIs.

However, this brings in additional lines into your code files which can get a bit troublesome when editing minor section of the files. But, then again, No pain, no gain. :beer:

Scikit-Learn has one of the best documentation I’ve ever seen anywhere in Python community.

Gitbook Django Girls is incredibly clean and Perfect. Gitbook is well suited for Tutorials with easy navigation and good code folding ability so that your documentation length doesn’t scare people.

1 Like
Documentation and Frontend Rejig
#14

Created a new thread under #moving-forward

1 Like
#15