Update 2021: Fixed links that died with Bitbuckets hosting.
I just found the excellent pydoc-info mode for emacs from Jon Waltman. It allows me to hit
C-h S in a python file and enter a module name to see the documentation right away. If the point is on a symbol (=module or class or function), I can just hit enter to see its docs.
In its default configuration (see the Readme) it “only” reads the python documentation. This alone is really cool when writing new python code, but it s not enough, since I often use third party modules.
And now comes the treat: If those modules use sphinx for documentation (≥1.1), I can integrate them just like the standard python documentation!
It took me some time to get it right, but now I have all the documentation for the inverse modelling framework I contribute to directly at my fingertips: Just hit
C-h S ENTER when I’m on some symbol and a window shows me the docs:
The text in this image is from Wouter Peters. Used here as short citation which should be legal almost everywhere under citation rules.
I want to save you the work of figuring out how to do that yourself, so here’s a short guide for integrating the documentation for your python program into emacs.
The prerequisite for integrating your own documentation is to use sphinx for documenting your code. See their tutorial for info how to set it up. As soon as sphinx works for you, follow this guide to integrate your docs in your emacs.
First get pydoc-info and the python infofile (adapt this to your local setup):
# get the mode cd ~/.emacs.d/libs hg clone https://hg.sr.ht/~arnebab/pydoc-info # and the pregenerated info-file for python wget http://www.draketo.de/dateien/python.info.gz gunzip python.info.gz sudo cp python.info /usr/share/info sudo install-info --info-dir=/usr/share/info python.info
To build the info file for python yourself, have a look at the Readme.
Now turn your own documentation into an info document and install it.
Sphinx uses a core configuration file named conf.py. Add the following to that file, replacing all values but index and False by the appropriate names for you project:
# One entry per manual page. # list of tuples (startdocname, # targetname, title, author, dir_entry, # description, category, toctree_only). texinfo_documents = [ ('index', # startdocname, keep this! 'TARGETNAME', # targetname u'Long Title', # title u'Author Name', # author 'Name in the Directory Index of Info', # dir_entry u'Long Description', # description 'Software Development', # cathegory False), # better keep this, too, i think. ]
Then call sphinx and install the info files like this (maybe adapted to your local setup):
sphinx-build -b texinfo source/ texinfo/ cd texinfo sudo install-info --info-dir=/usr/share/info TARGETNAME.info sudo cp TARGETNAME.info /usr/share/info/
Finally add the following to your .emacs (or wherever you store your personal adaptions):
; Show python-documentation as info-pages via C-h S (setq load-path (cons "~/.emacs.d/libs/pydoc-info" load-path)) (require 'pydoc-info) (info-lookup-add-help :mode 'python-mode :parse-rule 'pydoc-info-python-symbol-at-point :doc-spec '(("(python)Index" pydoc-info-lookup-transform-entry) ("(TARGETNAME)Index" pydoc-info-lookup-transform-entry)))
⚙ Babcom is trying to load the comments ⚙
This textbox will disappear when the comments have been loaded.
Note: To make a comment which isn’t a reply visible to others here, include a link to this site somewhere in the text of your comment. It will then show up here. To ensure that I get notified of your comment, also include my Sone-ID.
Link to this site and my Sone ID:
This spam-resistant comment-field is made with babcom.
The European Copyright directive threatens online communication in Europe.
But thanks to massive shared action earlier this year, the European parliament can still prevent the problems. For each of the articles there are proposals which fix them. The parliamentarians (MEPs) just have to vote for them. And since they are under massive pressure from large media companies, that went as far as defaming those who took action as fake people, the MEPs need to hear your voice to know that your are real.
If you care about the future of the Internet in the EU, please Call your MEPs.