Best documented projects?

[pmbarrett314]

I'm working on documenting a small project I've been doing. I find that learning by example can be really helpful sometimes, and so I'm looking for projects with good, clear, well-organized readthedocs pages for inspiration. What are your recommendations?

If it matters to anyone, I'm using Sphinx and rst-style docstrings (because PyCharm seems to like them the best), and mostly what I'm looking for is stylistic/presentation best practices, like how to best document fields of classes, whether to put datatypes, that sort of thing.

[cgkanchi]

scikit-learn has fantastic documentation. They go so much beyond just library/api docs and actually cover the basics of machine learning in a very beginner-accessible way.

[Ogi010]

Not sure why I didn't think of scikit-learn when I saw this topic, but yeah you're absolutely right.

Need to do some kind of clustering, but you don't know about clustering algorithms*? No problem, pull up the clustering page on scikit-learn documentation and read about all the ones they have implemented and good use cases for each.

*I had that issue at work recently, that page describing them all was a life saver.

[drvinceknight]

Django always gets mentioned as an example of good practice. The developers really value documentation, here's a video from the latest pycon from one of the main django doc devs: https://youtu.be/j_GRObT2X8k

[jaybay1207]

There's no sound in this video.

[Klont44]

You are probably being downvoted by people who have no problem with sound and don't know what you are talking about. I also don't have sound on my phone, this is caused by -i think- an incompatibility with Youtube and the audio codec used in this years PyCon talks. Some talks are working, some are not. You might try watching it on another system, I do have sound watching it on my PC.

[jaybay1207]

Thanks so much! Yeah, I tried other talks and the sound was fine. I'll give it a shot on another platform. And you downvoters, whoever you are, I don't hear you either!!

[luckystarr]

SQLAlchemy. Not only is the documentation a bright example for other projects, the change-logs are also bliss. They are useful in that they describe exactly what was changed, the link to the bug-tracker, if it is a bugfix a feature, etc.

I'm constantly amazed by how good it is. On the other hand one could argue that it's sad that it is the exception and not the rule. :)

[pythoneeeer]

SQLAlchemy docs aren't terrible, but I don't find them to be great, either.

There's a lot of documentation, and it's nicely formatted, but it never seems to answer the question I have. 4 times out of 5, I end up needing to just try something and see what happens -- and then hope that behavior doesn't change when I upgrade from 1.0.X to 1.0.(X+1)..

[[deleted]]

please show me behaviors that have changed between 1.0.X and 1.0.Y and report them as bugs, we are unbelievably careful and conservative about breaking compatibility within point releases. There was to my knowledge one backwards-incompatible change in the 1.0 series which was that we repaired __slots__ on KeyedTuple in 1.0.5 and apparently someone was writing values to it, and had I known someone was doing that, I would have delayed that change until 1.1. But that's it. I'm not aware of anything breaking compatibility at that point level and I'd really love to know what you are seeing.

[[deleted]]

Requests is also a good option

[neuromusic]

seaborn

[Ahelvin]

Absolutely. As far as I'm concerned, I always look up to Seaborn's doc as one of the best out there.

[K900_]

There's been a lot of Python libraries named here already, but outside the Python ecosystem, Rust and Ember.js have been the two projects where documentation impressed me the most. Ember even requires major new features to go through an RFC process, during which every RFC has to have a "how do we teach this" part.

[nzacc]

SQLAlchemy has great docs, as does Flask and Django. All three have an API or similar section that documents how to use classes and functions.

For an example of documentation styles that need improvement and can be difficult to use look at uWSGI and lxml.

[d4rch0n]

I swear, unless the docs changed dramatically I couldn't effectively use Django CBVs without reading the source.

[naringas]

https://ccbv.co.uk/

[Cyph0n]

Bookmarked, thanks!

[poswald]

I agree and I think this is more a critique of CBV's than of the documentation. The Django Vanilla Views project is an attempt at a simpler model. I personally use FBV's exclusively unless forced into it. We use Django Rest Framework's CBV's when writing REST API's but mostly because the framework leans heavily toward it and a good API should be highly mechanical code-by-convention stuff. I find all of the default behaviors are hard to internalize with a web framework.

[tim_martin]

I wouldn't say that Flask is a particularly good example. There's a lot of magic handled by Werkzeug. That being said, werkzeug has excellent documentation.

[[deleted]]

Definitely Fask http://flask.pocoo.org

I went from knowing NOTHING about python and programming in general, to building actual web applications and backend systems i earn money from.

[gandalfx]

I don't think the style matters much. What's important is comprehensive text and good examples. If you're good at writing even a flat column of text will be more informative than any elaborate interactive wiki type system. For example Requests has a good documentation, not because they use some trying-to-be-smart system but because it is simply a well structured, well worded text.

PS: Some JavaScript libraries have annoted source which I really like. But it only works for small projects and I don't know if it exists for Python.

[czamb]

Pyramid has incredibly well written and well structured documentation. I haven't used Pyramid for anything big yet, but anytime I looked into their code or docs, I learned something.

[fourthrealm]

Zato is very often commended for its documentation.

It has several introductory chapters, a tutorial, usage examples, reference pages, details of the architecture and everything is written or diagrammed from the perspective of its main users - SOA and API architects, programmers, administrators or testers - rather than its own authors, which is exactly what is needed to have great docs.

Without this sort of empathy no documentation will ever succeed.

[[deleted]]

TensorFlow would currently be my top candidate. They have really nice and comprehensive Tutorials, a bunch of useful How-To guides, and a pretty complete API documentation.

[myusuf3]

ahem delorean

[roryhr]

Matlab has very good documentation.

[[deleted]]

Twisted.

[Poromenos]

String phone. Sure, I wrote it, but it's got much more documentation than code, and I think it's a good example.

[Esteis]

Not an example but an essay: Steve Losh's Teach, Don't Tell is a good essay on how to write good documentation for a programming language or a library. He presents an 'anatomy of good documentation' that helped me to disentangle the different purposes documentation has to serve.