Hi everyone, Apologies in advance for the long message; I need to make sure all the relevant context is given.
I've started the migration of the documentation for Crunchy (http:// code.google.com/p/crunchy) to make use of Sphinx. In the process, I plan to add some new directives and thought they might be a useful addition to Sphinx. Rather than come up with some arbitrary "syntax" for the new directives, I thought it would be wise to ask on this list for suggestions - especially if there was interest to include the code within the normal Sphinx distribution. There are two sets of new directives I am considering for Sphinx - and currently using with Crunchy itself. The first is currently called (for Crunchy use) "getpythonsource" and, in its simplest form, is used as follows: .. getpythonsource:: relative/path/to/module.object It uses the inspect module to extract the source code for "object" from "module.py. One can simply use .. getpythonsource:: relative/path/to/module and the whole module will be included. In this way, it is a (partial) duplication of the existing "literalinclude" directive. However, it is clearly something that is Python specific and does not rely on knowing (or keeping track) of line numbers in a file to include the source of a specific "object". The object inclusion can even go to deeper levels such as .. getpythonsource:: relative/path/to/module.class.method ... i.e. anything supported by the inspect module. Before I introduce the second directive used by Crunchy, I should perhaps explain briefly what Crunchy is or does for people who are not familiar with it. Crunchy takes a static html (or rst) file and displays it within a browser window, adding "interactive elements", usually below code samples. The simplest interactive element is a Python interpreter: one can type in and execute Python code within the browser (Firefox) window and see the result back within the window. Crunchy detects relevant code samples as being inside html <pre> and use this to transform the page before feeding it to the browser. One can gives more precise instructions to Crunchy as to which interactive element to include by using the title attribute, such as <pre title="editor linenumber">, which would include an editor below the code sample, numbering the original code above, including a copy of the code within the editor (so that it could be changed and/or saved to a file, etc). It would also include a "code execution" button so that the code could be run by a Python interpreter as a normal script. There are a number of other interactive elements that one could include (doctest, unittest, ...) with some "very little added markup" (vlam) inserted in the title attribute. [Of course, if I may state the obvious, such interactive object is only relevant for html files to be viewed within a browser; this vlam would be totally irrelevant for pdf documents, etc.] So... the other directive supported by Crunchy for reStructuredText file is: .. crunchy:: vlam which is normally followed by some python code to be inserted in a <pre> element. Note that the getpythonsource directive above can also include vlam via: .. getpythonsource:: relative/path/to/module.object vlam ===== For my modification to sphinx, I see a few choices. The simplest (for me and to use only for my own purpose) is to simply add the two directives above as I already have the code working. However that is not very interesting ... Another option might be to make some changes to existing directives used by Sphinx. One possible choice would be to add an option to code- blocks as: .. code-block:: python :crunchy: vlam and/or one of the two options (in bracket): .. code-block:: python :getsource: relative/path/to/module.object [vlam] [:crunchy: vlam] I believe that these would not break any existing code and so would be totally transparent to the current sphinx users. However, since I am just starting to use sphinx, this may not be the best way to proceed. Does any one have suggestions as to what would be the best approach? Also, would there be interest in such an addition for Sphinx? (if so, I am not asking for others to write the code, I am volunteering to do it myself and contribute :-) Cheers, André --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
