I had been working on something to do the equations in rst, but it required some nasty hacks backing off to LaTeX to do the real work. I never really liked it. SVG does seem like the better way to go.
@jon schull: This does look like a very neat approach, and complements an earlier suggestion. The only downside is the external dependency on GraphViz. I'm trying (at least for now) to design things based on Python-only modules - preferably with no dependency outside of the standard library.
1:55 PM
After playing some more with the idea of embedding pictures in docstrings, I've settled on using dynamically created svg images instead of png images. The basic idea (which I'll write about in more details later) is to have something like
and have the docpicture module parse the "highly readable description" based on the syntax defined in some_type. Note that I chose this notation to be compatible with reStructuredText directives. The "highly readable description" will depend on the context. For example, the mathematically inclined will be able to read this:
.. docpictures:: equation e^{i\pi} = -1
while the following might be easy to understand by programmers:
..docpicture:: uml_sequence User --> Browser: clicks on a link Browser -> Crunchy: requests file Crunchy --> Browser: Authentication Request Browser --> Crunchy: Authentication Response note over Crunchy: Retrieves and processes file Crunchy -> Browser: Sends processed file Browser --> User: Displays file In this last example using the syntax of this site which generates the following picture: [Image]
(Btw, the picture above is generated automatically each time this page is loaded - so it depends on the availability of the server. I have used a static version of this picture in the documentation for Crunchy.)
Using svg to do graphics is fairly easy. Using svg as embedded objects in an html document requires a bit of searching on the internet. Creating such documents and displaying dynamically requires even more searching (or perhaps more careful reading...). The thing important to remember is to serve the document as "application/xhtml+xml" instead of the usual "text/html". I thought it would be useful to share an almost minimal working example (tested only on Firefox) and perhaps save some time for others that would like to do the same. Feel free to adapt it as you like.
"More on docpictures and (almost) minimal example of web server with inline svg"
6 Comments -
About the last sentence of my post, after re-reading the documentation carefully, I found out that all that is needed is to define something like
def log_message(self, *args):
''' will suppress the usual output'''
return
as a method of the request handler.
5:59 PM
I had been working on something to do the equations in rst, but it required some nasty hacks backing off to LaTeX to do the real work. I never really liked it. SVG does seem like the better way to go.
10:42 PM
It might be good to support a subset of the dot language but maybe making things simpler on the auto-layout side?
(http://www.graphviz.org/)
- Paddy.
5:37 AM
@paddy: Good idea. Ideally, one would do a Python port of WebDot.
7:16 AM
For embedding in html (and other things) it would also be good to consider this pidgeon-dot (based on python-like indentation)
http://tinyurl.com/6qrouc
1:43 PM
@jon schull:
This does look like a very neat approach, and complements an earlier suggestion. The only downside is the external dependency on GraphViz. I'm trying (at least for now) to design things based on Python-only modules - preferably with no dependency outside of the standard library.
1:55 PM