Transcripción
Extracto de la transcripción automática del vídeo realizada por YouTube.
Devlin please welcome her hi bonjour je m'appelle Catherine Devon Belva new see docs run run docs run I hope that came out right that's all the French I've got but thank you um all these slides are already online at tinyurl / run docs run and i
will give that URL again at the end and it has links to my github repo and everything else you're going to need so that's the only part that you'll need to write down and you don't even need to write it down yet so this talk is on executable
documentation which is a term that I just made up so I better define it I'm talking about documents that pull in real living code and execute that code and the results of that execution either validate or get incorporated into the document when you generate
that document or refresh that document or even when the reader is reading the document as for what a document is I want you to think really broadly here so I can get away with being in the education track yeah I'm talking about I wrote this package here's
how you use it but I'm also talking about educational documents like here's how you learn to program here's how you do this science problem here's how you do this math problem or organizational documentation here's how you request a new
laptop here's how we do our builds here's how you request funding to come to pike on these are all kinds of documents that can actually benefit from having code embedded in them why are we bothering aren't docs perfect well Doc's aren't
perfect a bunch of problems with them this doesn't address all of them but it addresses some of them one of the big problems is in accuracy that results from forgetfulness you think okay now i'm going to write the docs do to do it works like this it
works like this and you've already forgotten some of the details of how the program works and you write inaccuracies in or it was accurate to begin with but then time passes the code changes the organization changes and you forget to update the documents
also there's boredom most of us love to code it really engages our brain we get focused on the problem when we do a fairly good job of writing code and documentation is more like a chore resent it and that boredom shows through and the boredom spreads
to the reader and it's just not that engaging or relevant or fun to read so what we end up writing is historical fiction it wasn't even true to begin with is progressively less true and nobody's interested in reading it now I've never read
this book but it sure looks like it sucks so coding your documents can help fix this problem both in that the document can become self verifying the document lets you know when it's false or the document cannot be false because it's pulled straight
out of live working code also because it's code your brain will re-engage it wakes up it gets back into the problem it's right something that's relevant and that you care about and then the reader will end up caring about it and the quality of
your documentation will improve so to illustrate all this i'm going to i made up a fake little package called argument clinic and we're going to just run through how we might document up some users samples and checking on the software requirements
we're going to do that with four different technologies and because that's a lot to cover we're going to be going fast the examples are going to be really simple but i want to cover some of the basic boilerplate of using each of these and then
you can decide what might suit your project so the oldest one is doc tests this goes back to a previous millennium lost wisdom of the ages the idea of doc tests is simply that your your your doc strings can and should include usage samples those should show
the user how you use a piece of code and what the result should be that they can expect now in this case here's a piece of code where clearly the code is not complete it's not going to succeed at both of these it will answer this first one correctly
but it's not going to respond the way our doc test suggests it should our doc string suggested should and doc tests job is to go through pluck out those examples in doc strings and let you know when they fail so this is just a verification technique for
your docstrings docstrings get kind of a bad rap from testing snobs because they feel like it's not a good complete rigorous unit testing solution and fine going to concede that this is orthogonal to your unit testing solution not competing with nose or
pi dot test or anything else instead I'm renaming these two executable docstrings now the word test isn't even in there and the whole point is simply to make your doc strings relevant and accurate and more interesting and enjoyable to read so those
have been around forever next technology up Sphinx is more recent and this is actually part of why the documentation in the Python world has improved a ton because Sphinx takes a bunch of restructured text documents and generates a complex but not overly complex
a tree of documents that can refer to each other they include searchability and index ability really a pleasure to read and a pleasure to use Sphinx in itself isn't exactly what I'm calling executable documentation but there are some really worthwhile
[ ... ]
Nota: se han omitido las otras 2.651 palabras de la transcripción completa para cumplir con las normas de «uso razonable» de YouTube.