path: root/2022/captions/emacsconf-2022-python--short-hyperlinks-to-python-docs--eduardo-ochs--main.vtt

WEBVTT captioned by eduardo
Kind: captions:
Language: en-GB

00:00:00.000 --> 00:00:04.000
Hi! My name is Eduardo Ochs. I'm the author

00:00:04.000 --> 00:00:06.000
of an Emacs package called eev...

00:00:06.000 --> 00:00:10.000
and eev is about taking executable notes

00:00:10.000 --> 00:00:13.000
of everything that you do, and this

00:00:13.000 --> 00:00:16.000
presentation is about how I use this...

00:00:16.000 --> 00:00:18.000
how I finally found a way to take

00:00:18.000 --> 00:00:22.000
executable notes of what the python docs

00:00:22.000 --> 00:00:23.000
say.

00:00:23.000 --> 00:00:28.000
Let me explain that in another way. I've

00:00:28.000 --> 00:00:31.000
try to Learn Python many times, but

00:00:31.000 --> 00:00:34.000
hm, my brain is wired in a weird way, so

00:00:34.000 --> 00:00:37.000
it didn't work... and finally a few

00:00:37.000 --> 00:00:40.000
months ago I found a way of studying

00:00:40.000 --> 00:00:44.000
Python that finally clicked for me.

00:00:44.000 --> 00:00:47.000
The idea is that... well, it's here in

00:00:47.000 --> 00:00:50.000
the title - is a way to create short

00:00:50.000 --> 00:00:52.000
hyperlinks to the

00:00:52.000 --> 00:00:54.000
documentation of python.

00:00:54.000 --> 00:00:56.000
Here's an example.

00:00:56.000 --> 00:01:00.000
This file contains some some chunks

00:01:00.000 --> 00:01:03.000
of code from the Python tutorial and

00:01:03.000 --> 00:01:05.000
some links to the places in which

00:01:05.000 --> 00:01:07.000
I found these chunks of code.

00:01:07.000 --> 00:01:12.000
for example, if I run this link here

00:01:12.000 --> 00:01:14.000
it opens a certain page of the Python

00:01:14.000 --> 00:01:18.000
tutorial in my browser - note that it

00:01:18.000 --> 00:01:19.000
opens the local copy of the

00:01:19.000 --> 00:01:22.000
documentation -

00:01:22.000 --> 00:01:25.000
and if I

00:01:25.000 --> 00:01:29.000
run this link here it opens the source

00:01:29.000 --> 00:01:30.000
in .rst

00:01:30.000 --> 00:01:34.000
of the same page. So the first link opens

00:01:34.000 --> 00:01:37.000
the HTML and this one opens the

00:01:37.000 --> 00:01:39.000
RST. This is useful because in the

00:01:39.000 --> 00:01:40.000
beginning

00:01:40.000 --> 00:01:44.000
I was copying these chunks of code in

00:01:44.000 --> 00:01:46.000
the obvious way - I would simply

00:01:46.000 --> 00:01:50.000
visit the the documentation in HTML and

00:01:50.000 --> 00:01:51.000
I would mark

00:01:51.000 --> 00:01:54.000
a chunk... a snippet of code here and I

00:01:54.000 --> 00:01:58.000
would copy it to my notes.

00:01:58.000 --> 00:02:01.000
And then after a while I

00:02:01.000 --> 00:02:03.000
realized that it was much easier to

00:02:03.000 --> 00:02:07.000
simply go to the RST sources and to copy

00:02:07.000 --> 00:02:10.000
the chunks of code from there... and

00:02:10.000 --> 00:02:14.000
note that these links look quite similar.

00:02:14.000 --> 00:02:17.000
There's one difference here, that is

00:02:17.000 --> 00:02:20.000
this `r` that is prepended to the name

00:02:20.000 --> 00:02:23.000
of the function... the `r` means

00:02:23.000 --> 00:02:26.000
"open the RST"...

00:02:26.000 --> 00:02:30.000
and if I use the suffix `w` it means

00:02:30.000 --> 00:02:32.000
use the documentation on the web instead

00:02:32.000 --> 00:02:34.000
of using the local copy.

00:02:34.000 --> 00:02:36.000
So this one

00:02:36.000 --> 00:02:38.000
opens a local copy

00:02:38.000 --> 00:02:42.000
and this one

00:02:42.000 --> 00:02:46.000
takes a while

00:02:46.000 --> 00:02:49.000
and opens the

00:02:49.000 --> 00:02:52.000
the page of the documentation in the

00:02:52.000 --> 00:02:56.000
site of Python blah blah...

00:02:56.000 --> 00:02:58.000
and this thing here is

00:02:58.000 --> 00:03:02.000
executable in the usual eev sense, that

00:03:02.000 --> 00:03:05.000
we ca... if we type f8 several times here

00:03:05.000 --> 00:03:08.000
the f8s on the lines that start

00:03:08.000 --> 00:03:12.000
with red stars create a target buffer

00:03:12.000 --> 00:03:14.000
here... and in this case it creates a

00:03:14.000 --> 00:03:17.000
target buffer running Python, and if I

00:03:17.000 --> 00:03:20.000
type f8 on these other lines these are

00:03:20.000 --> 00:03:23.000
the lines are sent

00:03:23.000 --> 00:03:25.000
to that REPL.

00:03:25.000 --> 00:03:30.000
But anyway, let me go back.

00:03:30.000 --> 00:03:32.000
Most of the things that I'm going to

00:03:32.000 --> 00:03:35.000
present here are in the tutorial of this...

00:03:35.000 --> 00:03:37.000
package...

00:03:37.000 --> 00:03:41.000
we can go to the source code

00:03:41.000 --> 00:03:44.000
here in the eev directory - it's a file

00:03:44.000 --> 00:03:50.000
called eev-rstdoc.el but the best

00:03:50.000 --> 00:03:53.000
docs are in the tutorial, here...

00:03:53.000 --> 00:03:56.000
and the tutorial also has some

00:03:56.000 --> 00:03:58.000
executable

00:03:58.000 --> 00:04:02.000
chunks... some snippets of python

00:04:02.000 --> 00:04:05.000
code that are executable, but they

00:04:05.000 --> 00:04:07.000
don't have those nice colors... so

00:04:07.000 --> 00:04:11.000
apologies for that.

00:04:11.000 --> 00:04:13.000
We need to run this thing here to make

00:04:13.000 --> 00:04:15.000
everything work.

00:04:15.000 --> 00:04:17.000
This thing will define some functions

00:04:17.000 --> 00:04:19.000
with funny names that I will

00:04:19.000 --> 00:04:26.000
explain later.

00:04:26.000 --> 00:04:30.000
Let me explain something new.

00:04:30.000 --> 00:04:35.000
let's compare all these

00:04:35.000 --> 00:04:38.000
links here. They take this argument

00:04:38.000 --> 00:04:41.000
here and they expand the the argument in

00:04:41.000 --> 00:04:44.000
a certain way. For example this string is

00:04:44.000 --> 00:04:49.000
expanded to this long URL here... note that

00:04:49.000 --> 00:04:52.000
it got a prefix here,

00:04:52.000 --> 00:04:56.000
that's quite long... it got the .html here,

00:04:56.000 --> 00:04:59.000
and then the hash and the anchor here...

00:04:59.000 --> 00:05:03.000
and each one of the functions in the

00:05:03.000 --> 00:05:06.000
pydoc family expands this

00:05:06.000 --> 00:05:09.000
argument in a different way.

00:05:09.000 --> 00:05:12.000
The one that that opens the doc in the

00:05:12.000 --> 00:05:16.000
web uses another prefix -

00:05:16.000 --> 00:05:20.000
this one - and the one that opens the rst

00:05:20.000 --> 00:05:24.000
file ignores the part after the hash

00:05:24.000 --> 00:05:28.000
for technical reasons... I was never

00:05:28.000 --> 00:05:30.000
able to to find a good way to convert

00:05:30.000 --> 00:05:33.000
this hash into a string to search for,

00:05:33.000 --> 00:05:35.000
so to make something that goes to

00:05:35.000 --> 00:05:38.000
the right section in the link to the rst

00:05:38.000 --> 00:05:42.000
doc I have to convert by hand, and by

00:05:42.000 --> 00:05:46.000
trial and error, this thing here into a

00:05:46.000 --> 00:05:48.000
pointer to that section, like

00:05:48.000 --> 00:05:50.000
this one...

00:05:50.000 --> 00:05:55.000
in which the "_numeric-types:"

00:05:55.000 --> 00:05:58.000
is here.

00:05:58.000 --> 00:06:02.000
So all these links here are based on

00:06:02.000 --> 00:06:04.000
expansion, and this is easy to

00:06:04.000 --> 00:06:05.000
understand...

00:06:05.000 --> 00:06:08.000
but suppose that I want to

00:06:08.000 --> 00:06:11.000
create a link like this, or suppose that

00:06:11.000 --> 00:06:16.000
I'm browsing the docs here

00:06:16.000 --> 00:06:21.000
and I just I follow some some links...

00:06:21.000 --> 00:06:31.000
let me do something random here...

00:06:31.000 --> 00:06:34.000
suppose that I decide that this

00:06:34.000 --> 00:06:35.000
section is very interesting. How can I

00:06:35.000 --> 00:06:39.000
create a link to that? I can

00:06:39.000 --> 00:06:44.000
use this pilcrow symbol and the

00:06:44.000 --> 00:06:45.000
"Copy link address",

00:06:45.000 --> 00:06:49.000
and copy the link to

00:06:49.000 --> 00:06:51.000
my notes...

00:06:51.000 --> 00:06:55.000
and then the Python family...

00:06:55.000 --> 00:06:58.000
well, we saw the the functions in the

00:06:58.000 --> 00:07:00.000
Python family have a certain way - have

00:07:00.000 --> 00:07:03.000
several ways of expanding these

00:07:03.000 --> 00:07:06.000
short arguments... and they also have a

00:07:06.000 --> 00:07:07.000
certain way of

00:07:07.000 --> 00:07:11.000
shortening URLs like this one. If I type

00:07:11.000 --> 00:07:12.000
`M-x pdk` the message is this one.

00:07:12.000 --> 00:07:17.000
`pdk` is a mnemonic for

00:07:17.000 --> 00:07:20.000
"Python doc kill", and this

00:07:20.000 --> 00:07:23.000
"kill" means "copy to the kill ring"

00:07:23.000 --> 00:07:27.000
so if I type `M-x pdk` here it

00:07:27.000 --> 00:07:31.000
considers that this thing is a link

00:07:31.000 --> 00:07:34.000
to the python Docs, and it

00:07:34.000 --> 00:07:36.000
shortens this link in a certain way, and

00:07:36.000 --> 00:07:42.000
it kills a short link.

00:07:42.000 --> 00:07:45.000
I can insert the short link with C-y

00:07:45.000 --> 00:07:46.000
(yank)

00:07:46.000 --> 00:07:49.000
and then I can test this link to be sure

00:07:49.000 --> 00:07:52.000
that it points to where I want, and

00:07:52.000 --> 00:07:55.000
then I can delete this thing, and ta-da,

00:07:55.000 --> 00:07:57.000
now I have a short link, and of course I

00:07:57.000 --> 00:08:00.000
can modify this link by adding a suffix

00:08:00.000 --> 00:08:02.000
here...

00:08:02.000 --> 00:08:06.000
and in this case here

00:08:06.000 --> 00:08:09.000
I will have to change the identifier

00:08:09.000 --> 00:08:12.000
to something else...

00:08:12.000 --> 00:08:18.000
but I'm not going to do that now.

00:08:18.000 --> 00:08:20.000
This module of eev comes with three

00:08:20.000 --> 00:08:24.000
families predefined. One is a family that

00:08:24.000 --> 00:08:26.000
points to the the documentation of

00:08:26.000 --> 00:08:28.000
Python itself, another one points the

00:08:28.000 --> 00:08:30.000
documentation of SymPy, that is a program

00:08:30.000 --> 00:08:34.000
for symbolic computation, like for doing

00:08:34.000 --> 00:08:37.000
mathematics equations...

00:08:37.000 --> 00:08:40.000
and the other one points to the

00:08:40.000 --> 00:08:43.000
documentation of MatPlotLib.

00:08:43.000 --> 00:08:47.000
How do these families work?

00:08:47.000 --> 00:08:51.000
Each family has to be defined in two

00:08:51.000 --> 00:08:53.000
parts.

00:08:53.000 --> 00:08:55.000
Remember that

00:08:55.000 --> 00:08:58.000
eev has lots of functions

00:08:58.000 --> 00:09:03.000
like this one... this one

00:09:03.000 --> 00:09:06.000
is the most basic, and it is explained

00:09:06.000 --> 00:09:08.000
here, in this section of the main

00:09:08.000 --> 00:09:13.000
tutorial. This section explains that

00:09:13.000 --> 00:09:16.000
a sexp like this one produces lots of

00:09:16.000 --> 00:09:19.000
functions - produces a family of

00:09:19.000 --> 00:09:23.000
functions - and it does that by producing

00:09:23.000 --> 00:09:25.000
a certain chunk of code and then

00:09:25.000 --> 00:09:28.000
executing this chunk of code... and if we

00:09:28.000 --> 00:09:31.000
add a certain prefix here... `find-` and we

00:09:31.000 --> 00:09:35.000
execute this we can... instead of executing

00:09:35.000 --> 00:09:37.000
that chunk of code we can see what is

00:09:37.000 --> 00:09:39.000
that chunk of code. In the case of `code-c-d`

00:09:39.000 --> 00:09:43.000
it is this. It is a `setq`, several

00:09:43.000 --> 00:09:47.000
`defun`s, and some comments here, with

00:09:47.000 --> 00:09:49.000
links to the documentation.

00:09:49.000 --> 00:09:52.000
In the case of rstdoc it's the same.

00:09:52.000 --> 00:09:54.000
We have this function here that defines

00:09:54.000 --> 00:09:56.000
the function in the python family...

00:09:56.000 --> 00:09:59.000
and we can run this to understand what

00:09:59.000 --> 00:10:03.000
this `code-rstdoc` does.

00:10:03.000 --> 00:10:05.000
It creates this temporary buffer here...

00:10:05.000 --> 00:10:09.000
with lots of `defun`s, a `code-c-d` here,

00:10:09.000 --> 00:10:10.000
and lots of comments here... and the

00:10:10.000 --> 00:10:13.000
comments include some tests. For example

00:10:13.000 --> 00:10:16.000
we can use these functions here to test

00:10:16.000 --> 00:10:21.000
how the expansion works.

00:10:21.000 --> 00:10:23.000
And

00:10:23.000 --> 00:10:26.000
note that in this buffer here we don't

00:10:26.000 --> 00:10:28.000
have the paths that that this family

00:10:28.000 --> 00:10:31.000
uses. We don't have for example

00:10:31.000 --> 00:10:33.000
the URL that points to the site of

00:10:33.000 --> 00:10:36.000
Python, to the directory that contains

00:10:36.000 --> 00:10:40.000
the reference manual, or whatever... all

00:10:40.000 --> 00:10:42.000
these things are in another part of the

00:10:42.000 --> 00:10:44.000
definition of that family - that is a

00:10:44.000 --> 00:10:45.000
variable.

00:10:45.000 --> 00:10:48.000
If we execute this we go to the

00:10:48.000 --> 00:10:50.000
source code of eev-rstdoc,

00:10:50.000 --> 00:10:54.000
to the parts in which

00:10:54.000 --> 00:10:57.000
this variable is defined...

00:10:57.000 --> 00:10:59.000
and

00:10:59.000 --> 00:11:01.000
for each family we have a variable like

00:11:01.000 --> 00:11:02.000
this,

00:11:02.000 --> 00:11:05.000
whose value is a property

00:11:05.000 --> 00:11:07.000
list with several fields...

00:11:07.000 --> 00:11:09.000
these first fields are very easy to

00:11:09.000 --> 00:11:10.000
understand - they are used in the

00:11:10.000 --> 00:11:16.000
expansion... this one too. And these

00:11:16.000 --> 00:11:19.000
two fields are used in the shrinking -

00:11:19.000 --> 00:11:21.000
in the shortening - and

00:11:21.000 --> 00:11:25.000
this field here

00:11:25.000 --> 00:11:28.000
tells what is the name of the

00:11:28.000 --> 00:11:30.000
killing function

00:11:30.000 --> 00:11:33.000
so the fields of this thing here are

00:11:33.000 --> 00:11:34.000
used

00:11:34.000 --> 00:11:36.000
to generate...

00:11:36.000 --> 00:11:39.000
some fields are used to generate the

00:11:39.000 --> 00:11:41.000
code that appears here, and some fields

00:11:41.000 --> 00:11:44.000
are simply

00:11:44.000 --> 00:11:47.000
read by functions like this one, that

00:11:47.000 --> 00:11:51.000
consults the variable.

00:11:51.000 --> 00:11:53.000
Now the natural question is: how can we

00:11:53.000 --> 00:11:57.000
define new families? Or: how can we change

00:11:57.000 --> 00:11:59.000
a family like this one to point to

00:11:59.000 --> 00:12:03.000
another version of Python?

00:12:03.000 --> 00:12:06.000
There are some template-based functions

00:12:06.000 --> 00:12:09.000
for doing that. They are explained in

00:12:09.000 --> 00:12:10.000
this section of the tutorial...

00:12:10.000 --> 00:12:14.000
where is that?...

00:12:14.000 --> 00:12:17.000
oh God, it's far away...

00:12:17.000 --> 00:12:20.000
here.

00:12:20.000 --> 00:12:23.000
Suppose that we have a package foo, that

00:12:23.000 --> 00:12:25.000
we want to create a family that points

00:12:25.000 --> 00:12:27.000
to the docs

00:12:27.000 --> 00:12:31.000
of that package foo... so, we

00:12:31.000 --> 00:12:32.000
can execute this thing here, and it

00:12:32.000 --> 00:12:34.000
generates this

00:12:34.000 --> 00:12:37.000
this thing from a template.

00:12:37.000 --> 00:12:40.000
If we just want to modify a current

00:12:40.000 --> 00:12:42.000
definition we can run something like

00:12:42.000 --> 00:12:44.000
this - note that the family `:py`

00:12:44.000 --> 00:12:47.000
already exists, and instead of using

00:12:47.000 --> 00:12:51.000
placeholders in some of these

00:12:51.000 --> 00:12:53.000
URLs it will use the current values of

00:12:53.000 --> 00:12:55.000
the fields...

00:12:55.000 --> 00:12:59.000
so we can also use this modify

00:12:59.000 --> 00:13:01.000
existing families.

00:13:01.000 --> 00:13:05.000
Well these are the technical details.

00:13:05.000 --> 00:13:08.000
Now the natural question is: why do I

00:13:08.000 --> 00:13:12.000
want this? This doesn't

00:13:12.000 --> 00:13:14.000
any sense to me! Why should I

00:13:14.000 --> 00:13:15.000
try this?

00:13:15.000 --> 00:13:18.000
And the best answer: is for most people

00:13:18.000 --> 00:13:21.000
this way of using

00:13:21.000 --> 00:13:24.000
executable notes do not make any sense

00:13:24.000 --> 00:13:27.000
at all at first sight...

00:13:27.000 --> 00:13:30.000
so what I'm trying to do is: I'm trying

00:13:30.000 --> 00:13:33.000
to write to these tutorials with

00:13:33.000 --> 00:13:35.000
many examples that are very easy to run,

00:13:35.000 --> 00:13:38.000
and that examine data structures,

00:13:38.000 --> 00:13:40.000
and functions, and test things,

00:13:40.000 --> 00:13:46.000
and so on... so my main argument

00:13:46.000 --> 00:13:48.000
for convincing people to

00:13:48.000 --> 00:13:52.000
test this is: this is trivial to test -

00:13:52.000 --> 00:13:54.000
simply install eev and run this thing

00:13:54.000 --> 00:13:56.000
here, and run the examples, and probably

00:13:56.000 --> 00:13:58.000
you're going to find that this

00:13:58.000 --> 00:14:01.000
tutorial is fun to follow.

00:14:01.000 --> 00:14:03.000
So that's it! =)