# This file:
#   http://angg.twu.net/ORG/emacsconf2022-py.org.html
#   http://angg.twu.net/ORG/emacsconf2022-py.org
#           (find-angg "ORG/emacsconf2022-py.org")
# Author: Eduardo Ochs <eduardoochs@gmail.com>
#
# (defun epyo () (interactive) (find-angg "ORG/emacsconf2022-py.org"))
#
# Some eev-isms:
# (defun b  () (interactive) (find-TH "emacsconf2022-py"))
# (defun c  () (interactive) (eek "C-c C-e h h"))
# (defun o  () (interactive) (find-angg "ORG/emacsconf2022-py.org"))
# (defun oo () (interactive) (find-angg "emlua/README.org"))
# (defun cv () (interactive) (c) (v))
# (defun v  () (interactive) (brg     "~/ORG/emacsconf2022-py.html"))
#
#+OPTIONS: toc:nil


#+TITLE: Short hyperlinks to Python docs
#+AUTHOR: Eduardo Ochs
#+EMAIL: eduardoochs@gmail.com

If we have a local copy of the Python docs installed then it is easy
to define the three hyperlink functions in the Python program below,

#+begin_src python
# (find-pydoc  "tutorial/classes")
# (find-pydocw "tutorial/classes")
# (find-pydocr "tutorial/classes")
class MyVector:
    def __init__(v, x, y):
        v.x = x
        v.y = y
#+end_src

such that each one expands its argument in the right way, and the
first one opens the local URL
[[file:///usr/share/doc/python3.9-doc/html/tutorial/classes.html]] in the browser, the
second one opens [[https://docs.python.org/3/tutorial/classes.html]], and
the third one opens the RST source of those HTML pages in Emacs: the
file ~/<rstsourcedir>/tutorial/classes.rst.txt~.

The docs for Python are designed to be navigated in a browser. Suppose
that we start on the page [[https://docs.python.org/3/tutorial/classes.html][classes.html]] above, follow a couple of
hyperlinks, and then we find this other page that, ahem, is very
interesting and important and we /need/ to have hyperlinks to:

[[https://docs.python.org/3/reference/datamodel.html#object.__init__]]

The most obvious way to create elisp hyperlinks to that page is to
copy its URL to Emacs, edit it by hand to produce a ~(find-pydoc ...)~
hyperlink, duplicate that hyperlink twice, and add a "~w~" and a "~r~"
into the right places... but this is not very practical.

In this presentation I will show a practical way to handle that. It is
a new module of eev -- [[http://angg.twu.net/eev-current/eev-rstdoc.el.html][eev-rstdoc.el]] -- that performs both the
expansions needed by ~find-pydoc{,w,r}~ and the "shrinkings" that
convert URLs and filenames to short hyperlinks. Eev-rstdoc.el comes
with three "families" of hyperlinks, expansions, and shrinkings: one
for Python docs, one for SymPy, and one for MatPlotLib. It is easy to
add new families, and the parameters for expansion and shrinking in
each family are easy to configure.

For more info see [[http://angg.twu.net/emacsconf2022-py.html][this page]]. For a translation of the Python tutorial
to a format that has only executable examples and elisp hyperlinks,
see [[http://angg.twu.net/e/python.e.html#tut-numbers][this]].



# Local Variables:
# coding:  utf-8-unix
# modes:   (org-mode fundamental-mode)
# org-html-postamble:   nil
# End: